API Reference

Integrate Upwork functionalities to your web-based or mobile apps

Upwork Developers Site offers you access to our web services
to build your own applications and to integrate our features and workflow
to your dashboards, websites and management systems.
Please read Terms of use prior to using the Upwork Public API.

Featured functionalities

Getting started is easy. Check out our Getting Started section to learn about the core concepts of our API, such as supported authentication methods, languages and formats.

This page contains complete API reference documentation about our API technical implementation, just use your browser search or navigation panel on the left.

Have a question? Stop by the FAQs and Forum, or contact our Support team. Don’t forget to visit our Recent changes section to check out the new releases and features.

Libraries

Here you can find a list of available libraries for several languages.

API Entry Point

https://www.upwork.com/api

For Reports resources:

https://www.upwork.com/gds

Getting Started

Preparation

Before you start using Upwork API, you need to register your application and obtain your client credentials (a.k.a consumer key and consumer secret). To register, you just fill in basic information about your application and its intended use.

Note

Every new request for an API Key will be reviewed. For a quick positive decision, you need to comply the following conditions:

  1. your Upwork profile must have:
  • a. a valid name in your profile (no fake names, no company names)
  • b. a full valid address (including apartment number) - either in your personal or your company’s profile
  • c. a valid profile portrait
  1. provide a clear description on what you are planning using our APIs for (this info is required when you apply for a key). Do not forget add a note if you are going to use your application internally or publicly, or for any other purposes.
  2. agree to use the Upwork API in a manner that does not exceed a reasonable request volume. Our daily allowed limit is 40K reqs.
  3. refrain from using the Upwork logo, brand name, brand theme/colors and trademarked content in your application

Warning

Users who try registering a new application/key, but have a profile without a valid ID will be forced to go throw the ID verification process.

Application Permissions

When you register a new application, you are asked to define a list of permissions to access third-party resource data. You can later modify the permissions you request, but note that doing so makes all previously generated access tokens invalid. You will also have to request authorization from resource owners again.

Authentication

To access Upwork API, you need to go through an authentication process. Currently, we support the OAuth 1.0 method.

Note

You need to authenticate for all requests following the OAuth 1.0, RFC 5849.

The authentication process is simple. See the authentication section for a detailed description.

Libraries and Tools

A library is a collection of behavior implementations, written in a specific programming language. Libraries help you make system calls without the need to re-write code over and over again.

These are the libraries built specifically to support Upwork API:

On the right-hand side you can see the examples of how to make API calls with the chosen library.

Additionally, you can find a list of libraries for the language of your choice to help you with the OAuth mechanism here. To start using most of these libraries, you just need to provide your client credentials and the necessary URLs.

Try examples

$ mkdir upwork_project
$ cd upwork_project
$ virtualenv --no-site-packages ve
$ git clone https://github.com/upwork/python-upwork.git
$ cd python-upwork
$ source ../ve/bin/activate

Install latest version from master:

$ python setup.py install

Or you can use pip to install latest stable version from Pypi:

$ pip install python_upwork

Run the example application:

$ cd examples
$ python desktop_app.py
$ mkdir php_project
$ cd php_project
$ cat > composer.json <Enter>
{
  "name": "upwork/my-oauth-app",
  "require": {
    "upwork/php-upwork": "dev-master"
  }
}

$ composer.phar update
$ cp vendor/upwork/php-upwork/example/console-own-auth-lib.php myapp.php

Edit app.php to include your oAuth keys and run the application:

$ php myapp.php
$ gem install api-upwork
$ git clone https://github.com/upwork/ruby-upwork.git
$ cd ruby-upwork/examples

Edit myapp.rb to include your oAuth keys and run the application:

$ ruby myapp.rb

Use the interactive ruby console for debugging:

$ gem install pry
$ git clone https://github.com/upwork/java-upwork.git
$ cd java-upwork/example
$ make

Edit the upwork.properties file to include your oAuth keys and run the application:

$ make run
$ mkdir myapp
$ cd myapp
$ npm install upwork-api
$ cp node_modules/upwork-api/example/example.js example.js

Edit the example.js file to include your oAuth keys and run the application:

$ node example.js
$ cpan
cpan[1]> install Net::Upwork::API

We recommend installing the library from CPAN, otherwise you can download the source from the GIT repository.

$ perl myapp.pl
$ go get -u github.com/upwork/golang-upwork/api

We recommend installing using GO tools, otherwise you can download the source from the GIT repository.

$ go install myapp.go

Architecture style

Upwork follows the REST style. Thus, our API resources are accessed by explicitly using HTTP methods (GET, POST, PUT and DELETE) and following the protocol as defined by RFC 3986 standard.

Note

PUT and DELETE methods have couple important constraints:

  • • Methods are available only for JSON and XML requests.
  • Content-Type (RFC 1049) header must be equal to application/json (RFC 4627) for a JSON request.
  • Content-Type (RFC 1049) header must be equal to application/xml (RFC 2376) for an XML request .
  • • All parameters must be encoded in JSON format {"key1": "value1", "key2": "value2"} or XML format <request><key1>value1</key1></request> respectively.
  • • All parameters data must be sent as raw post data encoded as described above .

Request structure

The base URLs for all Upwork API requests are:

Note

All API requests must be made over HTTPS. API requests made over plain HTTP will be redirected to their equivalent HTTPS.

Cross-domain requests

Getting domain data from a domain different from the REST servers can cause failures. This is why we standardized our API for cross-domain requests. This makes it possible for you to use standard jQuery functions with the callback parameter.

Note

You must add &callback=? and oauth_xxx parameters to all your cross-domain requests, otherwise the API will not return standardized jQuery data. You can supply a ?callback parameter to any request in order to enable JSON-P wrapping. This is useful for cross-domain AJAX requests.

You can use this code to make JSON requests using jQuery:

$(document).ready(function(){
  $.getJSON("https://www.upwork.com/api/profiles/v2/search/jobs.json?q=java&callback=?&oauth_params=xxxxx",
       function(response){
          alert('Server Time: ' + response.server_time);
       });
});

You can also use the code below to make JSONP request with jQuery:

  $.ajax({
     url:"https://www.upwork.com/api/profiles/v2/search/jobs.json?q=java&callback=?&oauth_params=xxxxx",
     dataType: 'JSONP',
     success:function(json){
         alert("Success: "+json.server_time);
     },
     error:function(){
         alert("Error");
     },
});

Versioning

We version our API to support forward and backward compatibility. This means that new implementations don’t affect applications which depend on our API. The API version you target is defined the first time you make an API request. Every time we make backward-incompatible changes to the API, we release a new version. To avoid affecting your applications, we don’t modify your version until you’re ready to upgrade. Note that our versioning process is made at the resource level.

Our API supports three ways of requesting a version of the API (see options on the right-hand side).

Note

We also support locating the version number on the second sub-path (if needed due to framework requirements). For example: /api/v1/auth/info.json

Three ways of specifying a version for the API call:

standard (recommended)
the version is located on the third subpath in the URL:

/api/auth/v1/info.json

via ``X-Upwork-Version`` header (has higher priority):

X-Upwork-Version: v1

via ``Accept`` header (has lower priority)

Accept: application/vnd.upwork.api-v1+json

Response format

Our API supports both XML and JSON response formats. We suggest you append the format specifier (.json or .xml) to the request URI to explicitly select JSON or XML. Otherwise, the API may default to either format. You can also use the Accept request-header, passing application/xml (RFC3023) or application/json (RFC4627) to define the response format.

Response elements

All responses include at least two elements:

  • auth_user - Information about the user making the request
  • server_time - Server time, in UNIX timestamp format

Response properties are always one of the following data types:

integer
A positive or negative whole number
string
Unicode text
URL
A string that conforms to RFC 1738
timestamp
A date expressed as seconds elapsed since January 1st, 1970

Pagination

Many calls support pagination. Although details of pagination and ordering may differ (see specific information for each resource in the API reference), API calls that do support pagination mostly do so by using the page and paging parameters. The format of these parameters is: $offset;$count, for example: page=20;10

The default values are 0;10. Count can be restricted to <= N, where N is the maximum page size, found in the parameter description.

Encoding

We use UTF-8 encoding. UTF-8 encodes each Unicode character as a variable number of 1 to 4 octets, where the number of octets depends on the integer value assigned to the Unicode character. It is an efficient encoding of Unicode documents that use mostly US-ASCII characters because it represents each character in the range U+0000 through U+007F as a single octet.

UTF-8 is the default encoding for XML and since 2010, it has become the dominant character set on the Web.

Rate Limits

Rate limiting of the API is primarily considered on a per-IP basis. We allow you to make 40 requests per window per IP. We use 1min windows. When an application exceeds the rate limit for our APIs, we will return an HTTP 429Too Many Requests” response code. If your application gets rate limited, then it will be unblocked within a minute since the last request that got rate limited.

To avoid being rate limited, please use caching in your application. Store API responses in your application if you expect a lot of use. For example, don’t try to call the Upwork API on every page load. Instead, call the API infrequently and load the response into a local cache. When users hit your website load the cached version of the results.

Error Handling

Upwork API returns standard HTTP error codes and provides additional error information in the response body (when allowed by HTTP specification), and in the special HTTP headers.

Headers examples:

  • X-Upwork-Error-Code - Internal error code, useful in case you contact our Support team
  • X-Upwork-Error-Message - Additional error information

The following table describes the most common HTTP error messages you may receive and possible solutions.

400 - Bad Request

The request could not be understood by the server due to malformed syntax.

  • • You should not repeat the request without modifications.
  • • Check the error message and response body to obtain information about the possible reason.
  • • Visit our Documentation site to learn more about the requirements, limits and allowed values of the request parameters and fields.
401 - Unauthorized

The request requires user authentication.

  • • Check the error message and response body to obtain information about the possible reason.
  • • Authenticate by following OAuth 1.0 protocol.
  • • Visit our Authentication page to learn more about Upwork authentication process.
403 - Forbidden

The server understood the request, but is refusing to fulfill it.

  • • Authorization will not help and the request SHOULD NOT be repeated.
  • • Check the error message and response body to obtain information about the possible reason.
  • • Visit our Documentation site to learn more about the requirements, limits and allowed values of the request parameters and fields.
404 - Not Found

The Request-URI did not match any resource in the server.

  • • Check the error message and response body to obtain information about the possible error cause.
  • • Visit our Documentation site to learn more about the requirements, limits and allowed values of the request parameters and fields.
413 - Request Entity Too Large

The server is refusing to process a request because the request entity is larger than the server is able to process.

  • • Check the error message and response body to obtain information about the possible reason.
  • • The server MAY close the connection to prevent you from continuing the request. If the condition is temporary, you MAY try again.
  • • Visit our Documentation site to learn more about the requirements limits and allowed values of the request parameters and fields.
429 - Too Many Requests

The server is refusing to process a request because an application has sent too many requests in a given amount of time. Intended for use with rate limiting schemes.

  • • You should reduce the number of simultaneous requests.
  • • You should comply with our rate-limit-policy, i.e. avoid exceeding daily limits.

In case you are still unable to work the error out, contact our Support team. They are more than happy to help you further. Please, include the following information on your message:

  • • error code
  • • error message
  • • public key of your (web server) application
  • • Upwork username used in requests
  • • full URL, please include all parameters (keys, signature, token) and headers used
  • • time of request (if possible)
  • • method of the request (GET/POST/PUT/DELETE. Note that PUT and DELETE are overloaded via POST+http_method=<method>.)
  • • your environment (OS, library, programming language)
  • • how did you run the request? Mobile, desktop, console, web (for web please specify your browser), etc.
  • • response headers and HTTP status
  • • response body

Body example:

{
    server_time: 1320658441
    error: {
        status: "403" // equal to HTTP status
        code: "174"   // internal error code, useful in case you contact Support team
        message: "Insufficient permission to list offers" // additional error message
    }
}

Terminology

In order to use Upwork API, it is important to have a good understanding of the underlying concepts of Upwork Platform.

Users, clients, freelancers

User
An Upwork account holder. A user can have multiple roles simultaneously: client, freelancer, agency staffing manager, and so on. A user must be a single person and account sharing is not allowed. Others can be added to your company or agency.
Freelancer
A person who can apply to jobs, work, and get paid by clients via Upwork. In API parameters and arguments, sometimes the terms provider and contractor are used to mean freelancer. Those are legacy names for the term.
Client
A person who, as part of a company, can hire Upwork freelancers. In API parameters and arguments, sometimes the term buyer is used to mean client- it’s a synonym.
Agency contractor
There are two types of agency contractors. Exclusive agency contractors can only work on behalf of the agency. The agency controls all their earnings. They cannot control their rates. Non-exclusive agency contractors can work for multiple agencies and/or independently. An agency can only control their agency jobs. Agency contractors can access worked hours’ reports, but not their earnings reports.

Companies, teams, agencies

Company
A primary financial entity and organizational unit. Larger companies can request to be divided into multiple teams.
Team
A basic unit of organization. Members of the team can see each other and work on common tasks. Most permissions are also relative to the team. At the beginning, each company has one dedicated team room, but others can be added later.
Agency
Acts as intermediary between the client and the freelancer. The client still hires a specific person, but the contract is paid to the agency. Agency size and staffing manager involvement varies widely.

Job postings, offers and contracts

Job posting
Description of the work to be done and the application guidelines for freelancers.
Offer
Proposal of contract terms as part of the hiring process. It can be initiated by the client or the freelancer, but it must be agreed upon by both parties.
Contract
The terms and conditions that rule a particular job between a client and a freelancer.
Fixed-price contract
Flat-rate contract or payment for milestones. It is not covered by the Upwork Guarantee.
Hourly contract
Contract billed per hour based on the Work diary registry. It is covered by the Upwork Guarantee.
Charge Amount
The amount of money that is deducted from the company’s financial account (Upwork fee included).
Amount
The amount of money that a freelancer or an agency receives as payment (Upwork fee not included).
Work diary
The Work diary acts as a visual time card. It is the basis for Upwork’s automated weekly billing system. It shows clients hours worked and work-in-progress screenshots.

Roles and permissions

Permissions define what a user can do in the context of a given team or a company. All permissions are relative to the team room, except for owner, which is relative to the company.

Owner
The lead admin responsible for the company and all its teams. By default, the company creator is the owner, but ownership can be transferred by contacting Customer support. Only the owner can create additional teams within a company.
Admin
A user with permissions to: add and remove team members, control everyone’s permissions, and manage the team’s financial account.
Financial access
A user with full access to the team’s financial account. This user cannot control team members or permissions.
Hiring manager
A user with full client permissions to post jobs, invite to an interview, make offers, hire, set weekly limits, change rates, make payments, end contracts, and leave feedback.
Recruiter
A user with limited client permissions to post jobs, invite, interview, and manage candidates.
Staffing manager
A user with control over agency contractors’ job applications, rates and agency reports.

Authentication

To make API requests, you need authenticate to Upwork API. Currently, we support OAuth 1.0 authentication. All API requests MUST be signed following the RFC 5849 specification.

OAuth 1.0

The OAuth protocol enables websites or applications (clients) to access protected resources from a web service (server) via an API, without requiring resource owners to disclose their service provider credentials to the clients. For more information on the OAuth workflow process visit Beginner’s Guide to OAuth and the OAuth 1.0 Guide.

Client credentials

For each application you develop, you need to obtain new client credentials. These include a client identifier and a client shared-secret. You can request these credentials at https://www.upwork.com/services/api/apply while logged into your Upwork account. You will receive a public and a private key for each client identifier and client shared-secret you request.

Upwork OAuth 1.0 workflow

At a basic level, the OAuth 1.0 authentication process involves the following steps:

  1. Get Request token
  2. Get authorization from the resource owner and obtain a Verifier code
  3. Exchange Request token and Verifier for an Access Token
_images/oauth1.png

Below you will find the list of API calls needed for authentication.

Get request token

Returns

Returns a token/secret pair to be used for authorization and getting the access token. Example:

oauth_callback_confirmed=1&oauth_token=d6b9dba626bf43f187a2aed2d5f8e387&oauth_token_secret=517af7d4c335cc59

DEFINITION
client.auth.get_request_token()
$client->getRequestToken();

There’s no public method for getting request token in ruby-upwork, request token is retrieved during invocation of the authorization:

client.get_authorization_url()

There’s no public method for getting request token in java-upwork, request token is retrieved during invocation of the authorization:

client.getAuthorizationUrl();

There’s no public method for getting request token in node-upwork, request token is retrieved during invocation of the authorization:

api.getAuthorizationUrl(callbackUrl, callback);

There’s no public method for getting request token in perl-upwork, request token is retrieved during invocation of the authorization:

$api->get_authorization_url();

There’s no public method for getting request token in golang-upwork, request token is retrieved during invocation of the authorization:

client.GetAuthorizationUrl(callback);
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.auth.get_request_token()
$client = new \Upwork\API\Client($config);
$client->getRequestToken()
There’s no public method for getting request token in ruby-upwork, request token is retrieved during invocation of the authorization (see below). You can do it manually using the oAuth library if necessary. There’s no public method for getting request token in java-upwork, request token is retrieved during invocation of the authorization (see below). You can do it manually using the oAuth library if necessary. There’s no public method for getting request token in node-upwork, request token is retrieved during invocation of the authorization (see below). You can do it manually using the oAuth library if necessary. There’s no public method for getting request token in perl-upwork, request token is retrieved during invocation of the authorization (see below). You can do it manually using the oAuth library if necessary. There’s no public method for getting request token in golang-upwork, request token is retrieved during invocation of the authorization (see below). You can do it manually using the oAuth library if necessary.
EXAMPLE RESPONSE
Returns tuple of request_token and request_token_secret.
Array
(
    [authorize_uri] => /services/api/auth
    [token] => abcdefghijklmnopqrstuvwxyz123
    [token_secret] => 1a2b3c4defghi
)
See the Authorization section.

Authorize and get verifier

Upwork server needs to request authorization from the resource owner to grant you access to the required data. To do so, you need to redirect the resource owner to Upwork server’s authentication endpoint.

Returns

If the authorization is successful, this call returns a verifier. You can also check for the X-Upwork-Oauth-Verifier header in response.

If the resource owner is not currently logged in to Upwork, he/she is asked to do so at www.upwork.com/login?redir=https://www.upwork.com/services/api/auth....

Then, Upwork checks if the resource owner has already authorized your (web server) application.

  • • If the resource owner has not authorized your (web server) application, Upwork asks the resource owner if he/she wishes to do so.
  • • If your application is authorized, the resource owner is redirected to your (web server) application using the callback URL provided with the request, or, if empty, to the one registered for the client identifier used. The callback URL will have the following query parameters appended: ?oauth_token=...&oauth_verifier=.... For desktop applications, there’s no callback triggered. Instead, the verifier is shown to the resource owner in the browser window.
DEFINITION
client.auth.get_authorize_url()

This method does both authorizing and retrieving access token:

$client->auth();

This method does both authorizing and retrieving access token:

client.get_authorization_url()
client.getAuthorizationUrl();
client.getAuthorizationUrl(String oauthCallback);
api.getAuthorizationUrl(callbackUrl, callback);
$api->get_authorization_url();
client.GetAuthorizationUrl("");
EXAMPLE REQUEST

get_authorize_url() method implicitly checks for the presence of request tokens, and obtains them if necessary, so you can omit calling get_request_token() manually and just call get_authorize_url() to get a verifier.

In desktop application flow, just copy the verifier manually from the browser.

In web application flow make a GET request to the generated authorization URL. Your registered callback URL is triggered and verifier is passed as oauth_verifier parameter.

import upwork
import requests
client = upwork.Client(public_key, secret_key, **credentials)
authorize_url = client.auth.get_authorize_url()

# Invoke the authorize url
requests.get(authorize_url)

# Or in the desktop flow
verifier = raw_input(
    'Please enter the verification code you get '
    'following this link:\n{0}\n\n> '.format(
        client.auth.get_authorize_url()))
$client = new \Upwork\API\Client($config);
$client->auth();
require 'upwork/api'

config = Upwork::Api::Config.new({
  'consumer_key'    => 'FILL_ME',
  'consumer_secret' => 'FILL_ME',
})

# setup client
client = Upwork::Api::Client.new(config)

authz_url = client.get_authorization_url
import com.Upwork.api.Config;
import com.Upwork.api.OAuthClient;

import java.util.Properties;

Properties keys = new Properties();
keys.setProperty("consumerKey", "FILL_ME");
keys.setProperty("consumerSecret", "FILL_ME");
Config config = new Config(keys);
OAuthClient client = new OAuthClient(config);
String authzUrl = client.getAuthorizationUrl();
var UpworkApi = require('upwork-api')
  , rl = require('readline');

var config = {
  'consumerKey' : 'FILL_ME',
  'consumerSecret' : 'FILL_ME'
};

var api = new UpworkApi(config);
var callbackUrl = 'http://my.callback.example.com';

api.getAuthorizationUrl(callbackUrl, function(error, url, requestToken, requestTokenSecret) {
  if (error) throw new Error('can not get authorization url, error: ' + error);

  // Authorize application
  var i = rl.createInterface(process.stdin, process.stdout);
  i.question('Please, visit an url ' + url + ' and enter a verifier: ', function(verifier) {
    i.close();
    process.stdin.destroy();
  });
});
use Net::Upwork::API;

$config = Net::Upwork::API::Config->new(
  'consumer_key'    => 'FILL_ME',
  'consumer_secret' => 'FILL_ME',
);

# setup api/client object
$api = Net::Upwork::API->new($config);

if (!$api->has_access_token()) {
    my $authz_url = $api->get_authorization_url();
}
import (
    "github.com/upwork/golang-upwork/api"
)

const cfgFile = "config.json"

client := api.Setup(api.ReadConfig(cfgFile))
if !client.HasAccessToken() {
    aurl := client.GetAuthorizationUrl("")
}
EXAMPLE RESPONSE
Get the verifier manually or extract it from the callback request.
Array
(
  [access_token] => abcdefghijklmnopqrstuvwxyz
  [access_secret] => a1b2c3defghijk
)

Get access token

Once you receive the request token and the resource owner’s authorization (verifier code), you are ready to request Upwork Server an Access token.

Returns

Returns the Access token.

Note

Once created, the Access token never expires.

DEFINITION
client.auth.get_access_token({VERIFIER})
$client->auth();
client.get_access_token(verifier)
client.getAccessTokenSet(String verifier);
api.getAccessToken(
  requestToken, requestTokenSecret,
  verifier, callback);
$api->get_access_token($verifier);
client.GetAccessTokenSet(verifier)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
verifier = raw_input(
    'Please enter the verification code you get '
    'following this link:\n{0}\n\n> '.format(
        client.auth.get_authorize_url()))

access_token, access_token_secret = client.auth.get_access_token(verifier)
$client = new \Upwork\API\Client($config);
$client->auth();
require 'upwork/api'

config = Upwork::Api::Config.new({
  'consumer_key'    => '',
  'consumer_secret' => '',
})

# setup client
client = Upwork::Api::Client.new(config)

authz_url = client.get_authorization_url

puts "Visit the authorization url and enter the oauth_verifier for further authorization:"
puts authz_url

verifier = gets.strip
access_token = client.get_access_token(verifier)
import com.Upwork.api.Config;
import com.Upwork.api.OAuthClient;

import java.util.Properties;
import java.util.Scanner;

Properties keys = new Properties();
keys.setProperty("consumerKey", "FILL_ME");
keys.setProperty("consumerSecret", "FILL_ME");
Config config = new Config(keys);
OAuthClient client = new OAuthClient(config);
String authzUrl = client.getAuthorizationUrl();

Scanner scanner = new Scanner(System.in);

System.out.println(authzUrl);
System.out.println("1. Copy paste the following url in your browser : ");
System.out.println(authzUrl);
System.out.println("2. Grant access ");
System.out.println("3. Copy paste the oauth_verifier parameter here :");

String oauth_verifier = scanner.nextLine();
scanner.close();

String verifier = null;
try {
    verifier = URLDecoder.decode(oauth_verifier,"UTF-8");
}
catch (Exception e) {
    e.printStackTrace();
}

HashMap<String, String> token = client.getAccessTokenSet(verifier);
var UpworkApi = require('upwork-api')
  , rl = require('readline');

var config = {
  'consumerKey' : 'FILL_ME',
  'consumerSecret' : 'FILL_ME'
};

var api = new UpworkApi(config);
var callbackUrl = 'http://my.callback.example.com';

api.getAuthorizationUrl(callbackUrl, function(error, url, requestToken, requestTokenSecret) {
  if (error) throw new Error('can not get authorization url, error: ' + error);

  // Authorize application
  var i = rl.createInterface(process.stdin, process.stdout);
  i.question('Please, visit an url ' + url + ' and enter a verifier: ', function(verifier) {
    i.close();
    process.stdin.destroy();

    // Get access token/secret pair
    api.getAccessToken(requestToken, requestTokenSecret, verifier, function(error, accessToken, accessTokenSecret) {
      if (error) throw new Error(error);

      // Here you can store access token in safe place

    });
  });
});
use Net::Upwork::API;

$config = Net::Upwork::API::Config->new(
  'consumer_key'    => 'FILL_ME',
  'consumer_secret' => 'FILL_ME',
);

# setup api/client object
$api = Net::Upwork::API->new($config);

if (!$api->has_access_token()) {
    my $authz_url = $api->get_authorization_url();

    print "Visit the authorization url and provide oauth_verifier for further authorization\n";
    print $authz_url . "\n";
    $| = "";
    $verifier = <STDIN>;

    my $token = $api->get_access_token($verifier);
    # store access token data in safe place!
}
import (
    "fmt"
    "bufio"
    "os"

    "github.com/upwork/golang-upwork/api"
)

const cfgFile = "config.json"

func main() {
    client := api.Setup(api.ReadConfig(cfgFile))
    if !client.HasAccessToken() {
        aurl := client.GetAuthorizationUrl("")
        // read verifier
        reader := bufio.NewReader(os.Stdin)
        fmt.Println("Visit the authorization url and provide oauth_verifier for further authorization")
        fmt.Println(aurl)
        verifier, _ := reader.ReadString('\n')

        // get access token
        token := client.GetAccessToken(verifier)
        // store access token data in safe place!
    }
}
EXAMPLE RESPONSE
Returns a tuple of oauth_access_token and oauth_access_token_secret.
Array
(
  [access_token] => abcdefghijklmnopqrstuvwxyz
  [access_secret] => a1b2c3defghijk
)
=> #<OAuth::AccessToken:0x00000002553e10
 @consumer=
  #<OAuth::Consumer:0x0000000269f5a8
   @http=#<Net::HTTP www.upwork.com:443 open=false>,
   @http_method=:post,
   @key="abcdef123456789",
   @options=
    {:signature_method=>nil,
     :request_token_path=>"/api/auth/v1/oauth/token/request",
     :authorize_path=>"/services/api/auth",
     :access_token_path=>"/api/auth/v1/oauth/token/access",
     :proxy=>nil,
     :scheme=>:header,
     :http_method=>:post,
     :oauth_version=>"1.0",
     :site=>"https://www.upwork.com"},
   @secret="">,
 @params=
  {:oauth_token=>"abcdef123456789",
   "oauth_token"=>"abcdef123456789",
   :oauth_token_secret=>"abcdef123456789",
   "oauth_token_secret"=>"abcdef123456789"},
 @secret="abcdef123456789",
 @token="abcdef123456789">
HashMap<String, String>
{token=abcdefghijklmnopqrstuvwxyz1234567890,
 secret=abcdef0123456789}
You get error message, access token and access token secret as arguments in your callback function.
{
  'access_token' => 'abcdefghijklmnopqrstuvwxyz',
  'access_secret' => 'a1b2c3defghijk'
}
&{abcdefghijklmnopqrstuvwxyz a1b2c3defghijk map[]}

Required OAuth 1.0 parameters

Each API request must include a list of OAuth parameters (all the descriptions and meanings of parameters are defined by the OAuth specification at RFC 5849):

  • • oauth_consumer_key
  • • oauth_signature
  • • oauth_nonce
  • • oauth_signature_method (persistent constant equal to HMAC-SHA1)
  • • oauth_timestamp
  • • oauth_token
  • • any additional parameters for the specific API request.

Here is an example of a simple API request based on an authorized OAuth session:

/api/team/v1/teamrooms/upwork.json?oauth_signature=jL08juSnj9FQDzHY6%2BB4yr25QiA%3D& oauth_consumer_key=5bba83419248517d7883285e2b5976b1&oauth_nonce=580f9c6d6b490fb16bb5dd29b5c& oauth_signature_method=HMAC-SHA1&oauth_timestamp=1292557402&oauth_token=6b3b412b60c4e7000329e990a4dbbb2c&online=all

Troubleshooting authentication issues

Authentication errors are the most common issues received by our Support team. Here are some troubleshooting tips you may want to try to solve frequent authentication issues and start using our API.

  • • Most OAuth signing issues are caused by an invalid format in the signature base string.
  • • If you use a header-based OAuth request, make sure that the HTTP authorization header is being properly setup and formatted according to the specific language you use. Remember that you SHOULD NOT repeat any of the oauth_* parameters in the POST body or URL of the request you are making. Parameters that begin with oauth_* SHOULD NOT be part of the POST body or query string.
  • • Don’t include unnecessary oauth_* parameters in the request.
  • • Use auth in all REST API methods that support it. All Upwork REST API methods require authentication and using auth ensures that the requests are evaluated within the context of your current user.
  • • Use valid endpoints.
  • • Make sure you are using the appropriate HTTP request method. Most calls to the Upwork API use POST or GET methods.
  • • If you use an OAuth library, make sure you select a well-supported one.
  • • Try making the request in another OAuth library or tool. Comparing successful and failed requests will help you identify what might be going wrong.
  • • Learn how to override the oauth_timestamp and oauth_nonce values in your OAuth library. Use this capability to replay signature generation scenarios for comparative analysis.
  • oauth_token and oauth_token_secret strings change when a user’s access moves between permission levels, or if a user denies your application access and then re-grants access. Never assume that the strings will remain constant.

The following are the most frequent authentication errors you may come across:

400 - Bad request

The request could not be understood by the server due to malformed syntax.

Suggestion: Review the error message and make the necessary modifications before retrying. You should not repeat the request without modifications.

  • • Can’t verify request, missing oauth_consumer_key or oauth_token.
  • • Can’t verify request signature, missing parameter.
  • • None of the signing methods is supported.
  • • Unsupported signature method.
  • • Expected OAuth version.
  • • Unsupported characters in host name.
  • • Unsupported scheme type, expected Timestamp is out of sequence.

401 - Unauthorized

User authentication is required and has failed or has not yet been provided.

Suggestion: Check the procedure for signature calculation.

  • • Verification of signature failed.

403 - Forbidden

The server understood the request, but is refusing to fulfill it.

Suggestion: Review the error message and make the necessary modifications before retrying. You should not repeat the request without modifications.

  • • Duplicate timestamp/nonce combination, possible replay attack.
  • • The consumer_key and token combination does not exist or is not enabled.

Users

This section describes resources that return information about users.

Authenticated User

Returns

Returns information about the currently authenticated user.

DEFINITION
client.auth.get_info()
$auth->getUserInfo();
auth.get_user_info()
auth.getUserInfo();
auth.getUserInfo(callback);
$auth->get_user_info();
auth.GetUserInfo()
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.auth.get_info()
$auth = new \Upwork\API\Routers\Auth($client);
$auth->getUserInfo();
auth = Upwork::Api::Routers::Auth.new(client)
auth.get_user_info
import com.Upwork.api.Routers.Auth;

Auth auth = new Auth(client);
auth.getUserInfo();
var Auth = require('upwork-api/lib/routers/auth').Auth;

var auth = new Auth(api);
auth.getUserInfo(function(error, data) {
  console.log(data);
});
my $auth = Upwork::Api::Routers::Auth->new($api);
$auth->get_user_info();
import ( authUpwork "github.com/upwork/golang-upwork/api/routers/auth" )

auth := authUpwork.New(client)
auth.GetUserInfo()
EXAMPLE RESPONSE
{
  'server_time': '1400662109',
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Bangkok',
    'timezone_offset': '25200'
  },
  'info': {
    'portrait_50_img': 'https://...',
    'ref': '525',
    'portrait_32_img': 'https://...',
    'has_agency': '0',
    'portrait_100_img': 'https://...',
    'company_url': '',
    'capacity': {
      'provider': 'yes',
      'buyer': 'yes',
      'affiliate_manager': 'no'
    },
    'location': {
      'city': 'San Francisco',
      'state': 'CA',
      'country': 'United States'
    },
    'profile_url': 'https://...'
  }
}

Referenced User

Returns

Returns the following information about the referenced user:

reference
reference to User object
The reference ID of the user
id
string
The literal ID of the user
first_name
string
The user’s first name
last_name
string
The user’s last name
timezone
string
The user’s time zone.
timezone_offset
integer
The time zone offset in seconds
is_provider
boolean
Indicates whether the user is a freelancer (can be hired) or not
status
string (“active”, “inactive”)
The status of the user
DEFINITION
client.hr.get_user(user_reference)
client.hr.get_user_me()
$users->getMyInfo();
$users->getSpecific( integer $userReference );
users.get_my_info()
users.get_specific(user_reference)
users.getMyInfo();
users.getSpecific(String userReference);
users.getMyInfo(callback);
users.getSpecific(userReference, callback);
$users->get_my_info();
$users->get_specific($user_reference);
users.GetMyInfo()
users.GetSpecific(userReference)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.get_user_me()
$users = new \Upwork\API\Routers\Organization\Users($client);
$users->getMyInfo();
users = Upwork::Api::Routers::Organization::Users.new(client)
users.get_my_info
import com.Upwork.api.Routers.Organization.Users;

Users users = new Users(client);
users.getMyInfo();
var Users = require('upwork-api/lib/routers/organization/users.js').Users;

var users = new Users(api);
users.getMyInfo(function(error, data) {
  console.log(data);
});
my $users = Upwork::Api::Routers::Organization::Users->new($api);
$users->get_my_info();
import ( usersUpwork "github.com/upwork/golang-upwork/api/routers/organization/users" )

users := usersUpwork.New(client)
users.GetMyInfo()
EXAMPLE RESPONSE
{
  'timezone': 'UTC+07:00 Bangkok, Jakarta, Hanoi',
  'status': 'active',
  'timezone_offset': '25200',
  'public_url': 'https://www.upwork.com/...',
  'last_name': 'Johnson',
  'email': 'my_upwork_username@example.com',
  'reference': '12345',
  'id': 'my_upwork_username',
  'is_provider': '1',
  'first_name': 'John',
  'profile_key': '...'
}

User Permissions

Returns

While permission and role information is contained in the permision field, this API returns a complete list of a team information for each team that the authorized user has access to. It is also important to consider that a user may have multiple roles within a team.

For example, a user who has full manager permissions within a team returns the following fields:

manage_finance
Access to the company or team financial details.
manage_affiliation
Access to the affiliate freelancers within a company or team.
manage_employment
Permission to start engagements (actually hire freelancers).
manage_recruiting
Permission to post new jobs and interview candidates.
DEFINITION
client.hr.get_user_roles()
$roles->getAll();
roles.get_all()
roles.get_by_specific_user(user_reference)
roles.getAll();
roles.getBySpecificUser(String reference);
roles.getAll(callback);
roles.getBySpecificUser(reference, callback);
$roles->get_all();
$roles->get_by_specific_user($user_reference);
roles.GetAll()
roles.GetBySpecificUser(reference)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.get_user_roles()
$roles = new \Upwork\API\Routers\Hr\Roles($client);
$roles->getAll();
roles = Upwork::Api::Routers::Hr::Roles.new(client)
roles.get_all
import com.Upwork.api.Routers.Hr.Roles;

Roles roles = new Roles(client);
roles.getAll();
var Roles = require('upwork-api/lib/routers/hr/roles.js').Roles;

var roles = new Roles(api);
roles.getAll(function(error, data) {
  console.log(data);
});
my $roles = Upwork::Api::Routers::Hr::Roles->new($api);
$roles->get_all();
import ( rolesUpwork "github.com/upwork/golang-upwork/api/routers/hr/roles" )

roles := rolesUpwork.New(client)
roles.GetAll()
EXAMPLE RESPONSE
{
  'userrole': [
    {
      'parent_team__id': '0123456789abcdf',
      'user__first_name': 'John',
      'permissions': {
        'permission': [
          'manage_finance',
          'manage_employment',
          'manage_recruiting',
          'manage_teamroom'
        ]
      },
      'company__reference': '12345',
      'user__last_name': 'Johnson',
      'team__is_hidden': '',
      'reference': '12345',
      'team__reference': '12345',
      'affiliation_status': 'none',
      'user__reference': '12345',
      'user__is_provider': '1',
      'parent_team__name': 'Upwork',
      'has_team_room_access': '1',
      'parent_team__reference': '12345',
      'team__id': '0123456789abcdf',
      'engagement__reference': '',
      'team__name': 'Upwork',
      'company__name': 'Upwork',
      'role': 'admin',
      'user__id': 'my_user_id',
      'is_owner': '1'
    },
    # ...
  ]
}

Public profiles

Public profiles resources allow you to search freelancer’s public profiles and get detailed information on a specific profile.

Search for Freelancers

Returns

Returns the list of the objects with information about each freelancer who matches the requested query and parameters.

DEFINITION
client.providers_v2.search_providers(
    data={PARAMS_DICT}, page_offset={OFFSET},
    page_size={COUNT})
$freelancers->find( array $params = array() );
freelancers.find(params)
freelancers.find(
  java.util.HashMap<String,String> params);
freelancers.find(params, callback);
$freelancers->find(%params);
freelancers.Find(params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
data = {'q': 'python', 'title': 'Web Developer'}
client.provider_v2.search_providers(data=data, page_offset=0, page_size=20)
$freelancers = new \Upwork\API\Routers\Freelancers\Search($client);
$params = array("q" => "python", "title" => "Web Developer");
$freelancers->find($params);
freelancers = Upwork::Api::Routers::Freelancers::Search.new(client)
params = {'q' => 'python', 'title' => 'Web Developer'}
freelancers.find(params)
import com.Upwork.api.Routers.Freelancers.Search;
import java.util.HashMap;

Search freelancers = new Search(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("q", "python");
params.put("title", "Web Developer");

freelancers.find(params);
var Search = require('upwork-api/lib/routers/freelancers/search.js').Search;

var freelancers = new Search(api);
var params = {'q': 'python', 'title': 'Web Developer'};
freelancers.find(params, function(error, data) {
  console.log(data);
});
my $freelancers = Upwork::Api::Routers::Freelancers::Search->new($api);
my %params = {'q' => 'python', 'title' => 'Web Developer'};
$freelancers->find(%params);
import ( searchUpwork "github.com/upwork/golang-upwork/api/routers/freelancers/search" )

freelancers := searchUpwork.New(client)
params := make(map[string]string)
params["q"] = "python"
params["title"] = "Web Developer"

freelancers.Find(params)
EXAMPLE RESPONSE
[
 {'categories2': ['Legal',
                  'Web & Mobile Development',
                  'Admin Support'],
  'country': 'India',
  'description': 'I do ...',
  'feedback': '4.8424790960452',
  'id': '~aaaa9999d3f394624e',
  'last_activity': 'June 17, 2014',
  'member_since': 'July 21, 2011',
  'name': 'John Johnson',
  'portfolio_items_count': '1',
  'portrait_50': 'https://...',
  'profile_type': 'Independent',
  'rate': '22.22',
  'skills': ['python',
              'django-framework',
              'mongodb',
              'jquery',
              'html5',
              'postgresql'],
 'test_passed_count': '3',
 'title': 'Web Developer'},
 {
   # Another freelancer
 },
 # ...
]

Get brief profile summary

Returns

Returns a brief summary of a freelancer profile.

DEFINITION
client.provider.get_provider_brief({PROVIDER_CIPHERTEXT})
$freelancers->getSpecific( string $key );
freelancers.get_specific_brief(key)
freelancers.getSpecificBrief(String key);
freelancers.getSpecificBrief(key, callback);
$freelancers->get_specific_brief($key);
freelancers.GetSpecificBrief(key)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.provider.get_provider_brief('~aaa99955d3f394624e')
$freelancers = new \Upwork\API\Routers\Freelancers\Profile($client);
$freelancers->getSpecific("~aaa99955d3f394624e");
freelancers = Upwork::Api::Routers::Freelancers::Profile.new(client)
freelancers.get_specific_brief('~aaa99955d3f394624e')
import com.Upwork.api.Routers.Freelancers.Profile;

Profile freelancers = new Profile(client);
freelancers.getSpecificBrief("~aaa99955d3f394624e");
var Profile = require('upwork-api/lib/routers/freelancers/profile.js').Profile;

var freelancers = new Profile(api);
freelancers.getSpecificBrief('~aa9955d3f394624e', function(error, data) {
  console.log(data);
});
my $freelancers = Upwork::Api::Routers::Freelancers::Profile->new($api);
$freelancers->get_specific_brief('~aaa99955d3f394624e');
import ( profileUpwork "github.com/upwork/golang-upwork/api/routers/freelancers/profile" )

freelancers := profileUpwork.New(client)
freelancers.GetSpecificBrief("~aaa99955d3f394624e")
EXAMPLE RESPONSE
{'ciphertext': '~aaa99955d3f394624e',
 'dev_ac_agencies': '',
 'dev_adj_score': '4.8424790960452',
 'dev_adj_score_recent': '4.83652565536548',
 'dev_billed_assignments': '16',
 'dev_city': 'Bangkok',
 'dev_country': 'Thailand',
 'dev_eng_skill': '5',
 'dev_groups': '',
 'dev_is_affiliated': '0',
 'dev_last_activity': 'June 17, 2014',
 'dev_last_worked': 'June 8, 2014',
 'dev_last_worked_ts': '1402185600000',
 'dev_portfolio_items_count': '1',
 'dev_portrait': 'https://...',
 'dev_portrait_100': 'https://...',
 'dev_portrait_32': 'https://...',
 'dev_portrait_50': 'https://...',
 'dev_profile_title': 'Web Developer',
 'dev_recno_ciphertext': '~aaa99955d3f394624e',
 'dev_short_name': 'John Johnson',
 'dev_timezone': 'UTC+07:00 Bangkok, Jakarta, Hanoi',
 'dev_tot_feedback': '10',
 'dev_total_hours': '48.6666666666667',
 'dev_ui_profile_access': 'Public'}

Get freelancer profile by key

Returns

There is a lot of information returned by this call and the best way to see what it actually means is pull data from a few providers and match up the fields. Most of the response fields are human readable. Here is some additional info that should help understand this response:

dev_profile_access
The status of the freelancer’s profile (public or private).
skill
Describes a skill that the freelancer has listed in his/her profile.
tsexam
Describes a test that the freelancer has taken and made public.
dev_score
Describes feedback that the freelancer has received after a job has been completed (or just closed).
dev_recent_rank_percentile
The freelancer’s rank at Upwork based on data from the last 90 days.
dev_active_interviews
The number of active interviews the freelancer is engaged in at the moment.
dev_total_hours
The total hours worked on Upwork by the freelancer.
experience
Describes the freelancer’s experience as listed in his/her profile under the Experience section.
assignment
Describes past assignments that are publicly viewable.
skill, skl_level
A skill level for the current freelancer. Values can be one of the following: Familiar, Good, Very Good, Proficient, Expert.
dev_ic, affiliated
Both these metrics return the same data. They were added at different times and both of them are kept for backward compatibility purposes.
DEFINITION
client.provider.get_provider({PROVIDER_CIPHERTEXT})
$freelancers->getSpecific( string $key );
freelancers.get_specific(key)
freelancers.getSpecific(String key);
freelancers.getSpecific(key, callback);
$freelancers->get_specific($key);
freelancers.GetSpecific(key)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.provider.get_provider('~aaa99955d3f394624e')
$freelancers = new \Upwork\API\Routers\Freelancers\Profile($client);
$freelancers->getSpecific("~aaa99955d3f394624e");
freelancers = Upwork::Api::Routers::Freelancers::Profile.new(client)
freelancers.get_specific('~aaa99955d3f394624e')
import com.Upwork.api.Routers.Freelancers.Profile;

Profile freelancers = new Profile(client);
freelancers.getSpecific("~aaa99955d3f394624e");
var Profile = require('upwork-api/lib/routers/freelancers/profile.js').Profile;

var freelancers = new Profile(api);
freelancers.getSpecific('~aa9955d3f394624e', function(error, data) {
  console.log(data);
});
my $freelancers = Upwork::Api::Routers::Freelancers::Profile->new($api);
$freelancers->get_specific('~aaa99955d3f394624e');
import ( profileUpwork "github.com/upwork/golang-upwork/api/routers/freelancers/profile" )

freelancers := profileUpwork.New(client)
freelancers.GetSpecific("~aaa99955d3f394624e")
EXAMPLE RESPONSE
{
   'assignments': {
     # ...
   },
   'ciphertext': '~~aaa9999db7b5808b',
   'dev_ac_agencies': '',
   'dev_adj_score': '4.99924101793537',
   'dev_adj_score_recent': '4.99981986177941',
   'dev_billed_assignments': '27',
   'dev_blurb': "My description",
   'dev_city': 'Bangkok',
   'dev_country': 'Thailand',
   'dev_eng_skill': '5',
   'dev_groups': {
     # ...
   },
   'dev_is_affiliated': '0',
   'dev_last_activity': 'June 20, 2014',
   'dev_last_worked': 'June 20, 2014',
   'dev_last_worked_ts': '1403222400000',
   'dev_portfolio_items_count': '11',
   'dev_portrait': 'https://...',
   'dev_portrait_100': 'https://...',
   'dev_portrait_32': 'https://...',
   'dev_portrait_50': 'https://...',
   'dev_profile_title': 'Python web developer +',
   'dev_recno_ciphertext': '~aaa999e7116ea7c92d',
   'dev_short_name': 'John Johnson',
   'dev_timezone': 'UTC+07:00 Bangkok, Jakarta, Hanoi',
   'dev_tot_feedback': '16',
   'dev_total_hours': '48.5',
   'dev_ui_profile_access': 'Public',
   'education': {
     # ...
   },
   'experiences': {
     # ...
   },
   'job_categories': {
     # ...
   },
   'permalink': '',
   'portfolio_items': {
     # ...
   },
   'skills': {
     # ...
   },
   'tsexams': {
     # ...
   }
}

Jobs

This section describes API resources to manage jobs and job-related activities. You can use these resources to search for jobs, post new jobs, list posted jobs, update jobs and delete them. You can also invite freelancers to a job interview.

Search for jobs

Returns

This resource allows third-party applications to search for public jobs on Upwork. The search parameters mirror the options available on the site.

DEFINITION
client.provider_v2.search_jobs(
    data={PARAMS_DICT}, page_offset=0, page_size=20)
$jobs->find( array $params = array() );
jobs.find(params)
jobs.find(
  java.util.HashMap<String,String> params);
jobs.find(params, callback);
$jobs->find(%params);
jobs.Find(params)
EXAMPLE REQUEST:
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
data = {'q': 'python', 'title': 'Web developer'}
client.provider_v2.search_jobs(data=data)
$jobs = new \Upwork\API\Routers\Jobs\Search($client);
$params = array("q" => "python", "title" => "Web Developer");
$jobs->find($params);
jobs = Upwork::Api::Routers::Jobs::Search.new(client)
params = {'q' => 'python', 'title' => 'Web Developer'}
jobs.find(params)
import com.Upwork.api.Routers.Jobs.Search;
import java.util.HashMap;

Search jobs = new Search(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("q", "python");
params.put("title", "Web Developer");

jobs.find(params);
var Search = require('upwork-api/lib/routers/jobs/search.js').Search;

var jobs = new Search(api);
jobs.find(params, function(error, data) {
  console.log(data);
});
my $jobs = Upwork::Api::Routers::Jobs::Search->new($api);
my %params = {'q' => 'python', 'title' => 'Web Developer'};
$jobs->find(%params);
import ( searchUpwork "github.com/upwork/golang-upwork/api/routers/jobs/search" )


jobs := searchUpwork.New(client)
params := make(map[string]string)
params["q"] = "python"
params["title"] = "Web Developer"

jobs.Find(params)
EXAMPLE RESPONSE
[
  {'budget': 750,
   'category2': 'Web & Mobile Development',
   'client': {'country': None,
              'feedback': 0,
              'jobs_posted': 1,
              'past_hires': 0,
              'payment_verification_status': None,
              'reviews_count': 0},
   'date_created': '2014-06-30T23:50:17+0000',
   'duration': None,
   'id': '~aaa9992d99e35a386e',
   'job_status': 'Open',
   'job_type': 'Fixed',
   'skills': ['css',
              'css3',
              'database-design',
              'database-programming',
              'english',
              'html',
              'javascript',
              'mysql',
              'php',
              'python'],
   'snippet': u"Need a custom website <...>",
   'subcategory2': 'Web Development',
   'title': 'Looking for highly skilled web developer',
   'url': 'http://...',
   'workload': '30+ hrs/week'},
   {
     # Another job
     # ...
   },
   # ...
 ]

List jobs

Returns

If successful, the resource returns a list of jobs.

DEFINITION
client.hr.get_jobs(
    buyer_team_reference, include_sub_teams=False,
    status=None, created_by=None, created_time_from=None,
    created_time_to=None, page_offset=0, page_size=20,
    order_by=None)
$jobs->getList( array $params );
jobs.get_list(params)
jobs.getList(
  java.util.HashMap<String,String> params);
jobs.getList(params, callback);
$jobs->get_list(%params);
jobs.GetList(params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.get_jobs('~abcdef')
$jobs = new \Upwork\API\Routers\Hr\Jobs($client);
$params = array("buyer_team__reference" => "~abcdef");
$jobs->getList($params);
jobs = Upwork::Api::Routers::Hr::Jobs.new(client)
params = {'buyer_team__reference' => '~abcdef'}
jobs.get_list(params)
import com.Upwork.api.Routers.Hr.Jobs;
import java.util.HashMap;

Jobs jobs = new Jobs(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("buyer_team__reference", "~abcdef");

jobs.getList(params);
jobs.getList(callback);
var Jobs = require('upwork-api/lib/routers/hr/jobs.js').Jobs;

var jobs = new Jobs(api);
var params = {'buyer_team__reference': '~abcdef'};
jobs.getList(params, function(error, data) {
  console.log(data);
});
my $jobs = Upwork::Api::Routers::Hr::Jobs->new($api);
my %params = {'buyer_team__reference' => '~abcdef'};
$jobs->get_list(%params);
import ( jobsUpwork "github.com/upwork/golang-upwork/api/routers/hr/jobs" )


jobs := jobsUpwork.New(client)
params := make(map[string]string)
params["buyer_team__reference"] = "~abcdef"

jobs.GetList(params)
EXAMPLE RESPONSE
{
  'lister': {
    'paging': {'count': '20', 'offset': '0'},
    'query': '',
    'sort': {'sort': {'sort': ['created_time', 'asc']}},
    'total_items': '5'
  },
  'jobs': [
    {
      'attachment_file_url': '',
      'budget': '5',
      'buyer_company__name': 'My Company',
      'buyer_company__reference': '1040945',
      'buyer_team__name': 'My Company',
      'buyer_team__reference': '1040945',
      'cancelled_date': '1380067200000',
      'category2': 'Web, Mobile & Software Dev',
      'created_time': '1377423220000',
      'description': 'Testing some functionality',
      'duration': '',
      'end_date': '1380067200000',
      'filled_date': '',
      'job_ref_ciphertext': '~12345abcdf',
      'job_type': 'fixed-price',
      'keep_open_on_hire': '',
      'num_active_candidates': '0',
      'num_candidates': '0',
      'num_new_candidates': '0',
      'preference_candidate_type': 'individuals',
      'public_url': 'https://...',
      'reference': '~12345abcdf',
      'skills': '',
      'start_date': '1377388800000',
      'status': 'cancelled',
      'subcategory2': 'Web & Mobile Development',
      'title': 'Test python-upwork',
      'visibility': 'invite-only'
    }
  ]
}

Get job by key

Returns

This resource returns the following details on the referenced job:

title
The title of the job.
job_type
The job type.
description
The description of the job.
public_url
The public URL of the job.
created_time
The time when the job was created.
created_by
The ID of the user who created the job.
start_date
The intended start date of the job.
end_date
The intended end date of the job.
filled_date
The date when the job was filled.
cancelled_date
The date when the job was cancelled.
buyer_team__reference
The reference ID for the client’s team that posted the job.
buyer_team__id
The name of the client’s team that posted the job.
buyer_company__reference
The reference ID for the company of the client’s team.
buyer_company__name
The name of the company of the client’s team.
visibility
The visibility of the job.
budget
The intended budget, if job fixed price.
duration
The intended duration, if job is hourly tracked.
category2
The category (V2) of the job.
subcategory2
The subcategory (V2) of the job.
num_candidates
The number of candidates.
num_active_candidates
The number of active candidates.
num_new_candidates
The number of new candidates.
status
The status of the job.
DEFINITION
client.hr.get_job(job_reference)
$jobs->getSpecific( string $key );
jobs.get_specific(key)
jobs.getSpecific(String key);
jobs.getSpecific(String key);
$jobs->get_specific($key);
jobs.GetSpecific(key)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.get_job('~12345abcdf')
$jobs = new \Upwork\API\Routers\Hr\Jobs($client);
$jobs->getSpecific("~12345abcdf");
jobs = Upwork::Api::Routers::Hr::Jobs.new(client)
jobs.get_specific('~12345abcdf')
import com.Upwork.api.Routers.Hr.Jobs;

Jobs jobs = new Jobs(client);
jobs.getSpecific("~12345abcdf");
var Jobs = require('upwork-api/lib/routers/hr/jobs.js').Jobs;

var jobs = new Jobs(api);
jobs.getSpecific('~12345abcdf', function(error, data) {
  console.log(data);
});
my $jobs = Upwork::Api::Routers::Hr::Jobs->new($api);
$jobs->get_specific('~12345abcdf');
import ( jobsUpwork "github.com/upwork/golang-upwork/api/routers/hr/jobs" )

jobs := jobsUpwork.New(client)
jobs.GetSpecific("~12345abcdf")
EXAMPLE RESPONSE
{
  'attachment_file_url': '',
  'budget': '5',
  'buyer_company__name': 'My Company',
  'buyer_company__reference': '1040945',
  'buyer_team__name': 'My Company',
  'buyer_team__reference': '1040945',
  'cancelled_date': '1380067200000',
  'category2': 'Web, Mobile & Software Dev',
  'created_time': '1377423220000',
  'description': 'Testing some functionality',
  'duration': '',
  'end_date': '1380067200000',
  'filled_date': '',
  'job_type': 'fixed-price',
  'keep_open_on_hire': '',
  'num_active_candidates': '0',
  'num_candidates': '0',
  'num_new_candidates': '0',
  'preference_candidate_type': 'individuals',
  'public_url': 'https://...',
  'skills': '',
  'start_date': '1377388800000',
  'status': 'cancelled',
  'subcategory2': 'Web & Mobile Development',
  'title': 'Test python-upwork',
  'visibility': 'invite-only'
}

Post job

Returns

If successful, this resource returns a 200 OK message and the job reference number.

DEFINITION
client.hr.post_job(
    buyer_team_reference, title, job_type, description,
    visibility, budget=None,
    duration=None, start_date=None, end_date=None,
    skills=None, category2=None, subcategory2=None)
$jobs->postJob( array $params );
jobs.post_job(params)
jobs.postJob(
  java.util.HashMap<String,String> params);
jobs.postJob(params, callback);
$jobs->post_job(%params);
jobs.PostJob(params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.post_job('~12345abcdf', 'Test oAuth API create job',
'hourly', 'A description', 'public',
'Web Development', 'Web Programming', skills=['python', 'javascript'])
$jobs = new \Upwork\API\Routers\Hr\Jobs($client);
$params = array(
  "buyer_team__reference" => "~12345abcdf",
  "title" => "Test oAuth API create job",
  "job_type" => "hourly",
  "description" => "A description",
  "visibility" => "public",
  "category2" => "Web, Mobile & Software Dev",
  "subcategory2" => "Web Development",
  "skills" => "python;javascript"
);
$jobs->postJob($params);
jobs = Upwork::Api::Routers::Hr::Jobs.new(client)
params = {
  'buyer_team__reference' => '~12345abcdf',
  'title' => 'Test oAuth API create job',
  'job_type' => 'hourly',
  'description' => 'A description',
  'visibility' => 'public',
  'category2' => 'Web, Mobile & Software Dev',
  'subcategory2' => 'Web Development',
  'skills' => 'python;javascript'
}
jobs.post_job(params)
import com.Upwork.api.Routers.Hr.Jobs;
import java.util.HashMap;

Jobs jobs = new Jobs(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("buyer_team__reference", "~12345abcdf");
params.put("title", "Test oAuth API create job");
params.put("job_type", "hourly");
params.put("description", "A description");
params.put("visibility", "public");
params.put("category2", "Web, Mobile & Software Dev");
params.put("subcategory2", "Web Development");
params.put("skills", "python;javascript");

jobs.postJob(params);
var Jobs = require('upwork-api/lib/routers/hr/jobs.js').Jobs;

var jobs = new Jobs(api);
var params = {
  'buyer_team__reference': '~12345abcdf',
  'title': 'Test oAuth API create job',
  'job_type': 'hourly',
  'description': 'A description',
  'visibility': 'public',
  'category2': 'Web, Mobile & Software Dev',
  'subcategory2': 'Web Development',
  'skills': 'python;javascript'
};
jobs.postJob(params, function(error, data) {
  console.log(data);
});
my $jobs = Upwork::Api::Routers::Hr::Jobs->new($api);
my %params = {
  'buyer_team__reference' => '~12345abcdf',
  'title' => 'Test oAuth API create job',
  'job_type' => 'hourly',
  'description' => 'A description',
  'visibility' => 'public',
  'category2' => 'Web, Mobile & Software Dev',
  'subcategory2' => 'Web Development',
  'skills' => 'python;javascript'
};
$jobs->post_job(%params);
import ( jobsUpwork "github.com/upwork/golang-upwork/api/routers/hr/jobs" )


jobs := jobsUpwork.New(client)
params := make(map[string]string)
params["buyer_team__reference"] = "~12345abcdf"
params["title"] = "Test oAuth API create job"
params["job_type"] = "hourly"
params["description"] = "A description"
params["visibility"] = "public"
params["category2"] = "Web, Mobile & Software Dev"
params["subcategory2"] = "Web Development"
params["skills"] = "python;javascript"

jobs.PostJob(params)
EXAMPLE RESPONSE
{'auth_user': {'first_name': 'John',
               'last_name': 'Johnson',
               'timezone': 'Asia/Omsk',
               'timezone_offset': '25200'},
'job': {'public_url': 'https://...',
'reference': '~aaa999f4c68af61ed6'},
'server_time': 1404364847}

Update job

Returns

If successful, this resource returns a 200 OK message.

DEFINITION
client.hr.update_job(
    job_id, buyer_team_reference, title, description,
    visibility, budget=None, duration=None, start_date=None,
    end_date=None, status=None, category2=None, subcategory2=None)
$jobs->editJob( string $key, array $params );
jobs.edit_job(key, params)
jobs.editJob(
  String key,
  java.util.HashMap<String,String> params);
jobs.editJob(key, params, callback);
$jobs->edit_job($key, %params);
jobs.EditJob(key, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
job_ref = '~abcd12345'
team_ref = '1234567'
client.hr.update_job(job_ref, team_ref, 'Test oAuth API create job', '(Updated) Create job via oAuth api',
'public', category2='Web, Mobile & Software Dev', subcategory2='Web Development', duration=100, status='open')
$jobs = new \Upwork\API\Routers\Hr\Jobs($client);
$params = array(
  "buyer_team__reference" => "~12345abcdf",
  "title" => "Test oAuth API create job",
  "description" => "Updated description",
  "visibility" => "public",
  "category2" => "Web, Mobile & Software Dev",
  "subcategory2" => "Web Development",
  "duration" => "100",
  "status" => "open"
);
$job_ref = "~abcd12345";
$jobs->editJob($job_ref, $params);
jobs = Upwork::Api::Routers::Hr::Jobs.new(client)
params = {
  'buyer_team__reference' => '~12345abcdf',
  'title' => 'Test oAuth API create job',
  'description' => 'Updated description',
  'visibility' => 'public',
  'category2' => 'Web, Mobile & Software Dev',
  'subcategory2' => 'Web Development',
  'duration' => '100',
  'status' => 'open'
}
job_key = '~abcd12345'
jobs.edit_job(job_key, params)
import com.Upwork.api.Routers.Hr.Jobs;
import java.util.HashMap;

Jobs jobs = new Jobs(client);
String jobKey = "~abcd12345";
HashMap<String, String> params = new HashMap<String, String>();
params.put("buyer_team__reference", "~12345abcdf");
params.put("title", "Test oAuth API create job");
params.put("description", "Updated description");
params.put("visibility", "public");
params.put("category2", "Web, Mobile & Software Dev");
params.put("subcategory2", "Web Development");
params.put("duration", "100");
params.put("status", "open");

jobs.editJob(jobKey, params);
var Jobs = require('upwork-api/lib/routers/hr/jobs.js').Jobs;

var jobs = new Jobs(api);
var key = '~abcd12345';
var params = {
  'buyer_team__reference': '~12345abcdf',
  'title': 'Test oAuth API create job',
  'description': 'Updated description',
  'visibility': 'public',
  'category2': 'Web, Mobile & Software Dev',
  'subcategory2': 'Web Development',
  'duration': '100',
  'status': 'open'
};
jobs.editJob(key, params, function(error, data) {
  console.log(data);
});
my $jobs = Upwork::Api::Routers::Hr::Jobs->new($api);
my %params = {
  'buyer_team__reference' => '~12345abcdf',
  'title' => 'Test oAuth API create job',
  'description' => 'Updated description',
  'visibility' => 'public',
  'category2' => 'Web, Mobile & Software Dev',
  'subcategory2' => 'Web Development',
  'duration' => '100',
  'status' => 'open'
};
my $job_key = '~abcd12345';
$jobs->edit_job($job_key, %params);
import ( jobsUpwork "github.com/upwork/golang-upwork/api/routers/hr/jobs" )


jobs := jobsUpwork.New(client)
jobKey = "~abcd12345";
params := make(map[string]string)
params["buyer_team__reference"] = "~12345abcdf"
params["title"] = "Test oAuth API create job"
params["description"] = "Updated description"
params["visibility"] = "public"
params["category2"] = "Web, Mobile & Software Dev"
params["subcategory2"] = "Web Development"
params["duration"] = "100"
params["status"] = "open"

jobs.EditJob(jobKey, params)
EXAMPLE RESPONSE
{'auth_user': {'first_name': 'John',
               'last_name': 'Johnson',
               'timezone': 'Asia/Omsk',
               'timezone_offset': '25200'},
'job': {'message': 'updated'},
'server_time': 1404365740}

Cancel job

Returns

If successful, this resource returns a 200 OK message.

DEFINITION
client.hr.delete_job(job_id, reason_code)
$jobs->deleteJob( string $key, array $params );
jobs.delete_job(key, params)
jobs.deleteJob(
  String key,
  java.util.HashMap<String,String> params);
jobs.deleteJob(key, params, callback);
$jobs->delete_job($key, %params);
jobs.DeleteJob(key, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.delete_job('~abcdf12345', 41)
$jobs = new \Upwork\API\Routers\Hr\Jobs($client);
$params = array("reason" => "41");
$job_ref = "~abcd12345";
$jobs->deleteJob($job_ref, $params);
jobs = Upwork::Api::Routers::Hr::Jobs.new(client)
params = {'reason' => '41'}
job_key = '~abcd12345'
jobs.delete_job(job_key, params)
import com.Upwork.api.Routers.Hr.Jobs;
import java.util.HashMap;

Jobs jobs = new Jobs(client);
String jobKey = "~abcd12345";
HashMap<String, String> params = new HashMap<String, String>();
params.put("reason", "41");

jobs.deleteJob(jobKey, params);
var Jobs = require('upwork-api/lib/routers/hr/jobs.js').Jobs;

var jobs = new Jobs(api);
var key = '~abcd12345';
var params = {'reason': '41'};
jobs.deleteJob(key, params, function(error, data) {
  console.log(data);
});
my $jobs = Upwork::Api::Routers::Hr::Jobs->new($api);
my %params = {'reason' => '41'};
my $job_key = '~abcd12345';
$jobs->delete_job($job_key, %params);
import ( jobsUpwork "github.com/upwork/golang-upwork/api/routers/hr/jobs" )


jobs := jobsUpwork.New(client)
jobKey = "~abcd12345";
params := make(map[string]string)
params["reason"] = "41"

jobs.DeleteJob(jobKey, params)
EXAMPLE RESPONSE
{'auth_user': {'first_name': 'John',
               'last_name': 'Johnson',
               'timezone': 'Asia/Omsk',
               'timezone_offset': '25200'},
 'job': {'message': 'deleted'},
 'server_time': 1404389886}

Get job profile

Returns

This resource returns an exhaustive list of attributes about the job. We recommend to pull data for a few freelancers and match up the fields to understand the meaning of the fields. Note that most of the response fields are human readable.

DEFINITION
client.job.get_job_profile(job_reference)
$profile->getSpecific( string $key );
profile.get_specific(key)
profile.getSpecific(String key);
profile.getSpecific(key, callback);
$profile->get_specific($key);
profile.GetSpecific(key)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.job.get_job_profile('~abcdf12345')
$profile = new \Upwork\API\Routers\Jobs\Profile($client);
$profile->getSpecific("~abcdf12345");
profile = Upwork::Api::Routers::Jobs::Profile.new(client)
profile.get_specific('~abcdf12345')
import com.Upwork.api.Routers.Jobs.Profile;

Profile profile = new Profile(client);
profile.getSpecific("~abcdf12345");
var Profile = require('upwork-api/lib/routers/jobs/profile.js').Profile;

var profile = new Profile(api);
profile.getSpecific('~abcdf12345', function(error, data) {
  console.log(data);
});
my $profile = Upwork::Api::Routers::Jobs::Profile->new($api);
$profile->get_specific('~abcdf12345');
import ( profileUpwork "github.com/upwork/golang-upwork/api/routers/jobs/profile" )

profile := profileUpwork.New(client)
profile.GetSpecific("~abcdf12345")
EXAMPLE RESPONSE
{'amount': '5',
 'assignment_info': '',
 'assignments': {'assignment': [{'as_ciphertext': '~abcdf1234567',
    'as_ciphertext_opening_recno': '~abcdf1234549353a08',
    'as_engagement_title': 'API test job',
    'as_from': '02/2014',
    'as_job_type': 'Fixed',
    'as_opening_title': 'API test job',
    'as_rate': '$0.00',
    'as_status': 'Active',
    'as_to': 'Present',
    'as_total_charge': '0',
    'as_total_hours': '0'},
   {'as_ciphertext': '~abcdf1234567',
    'as_ciphertext_opening_recno': '~abcdf123454e8f073e',
    'as_engagement_title': 'Testing an API',
    'as_from': '10/2013',
    'as_job_type': 'Fixed',
    'as_opening_title': 'Test create job via API',
    'as_rate': '$0.00',
    'as_status': 'Closed',
    'as_to': '10/2013',
    'as_total_charge': '1.11',
    'as_total_hours': '0',
    'feedback': {'comment': 'Test Company is a very good client, clean specs and nice to communicate.',
     'comment_is_public': '1',
     'score': '5.00',
     'scores': {'score': [{'description': 'competency and skills for the job, understanding of task complexities',
        'label': 'Skills',
        'score': '5'},
       {'description': 'quality of specifications/instructions',
        'label': 'Quality',
        'score': '5'},
       {'description': 'online presence on a consistent schedule',
        'label': 'Availability',
        'score': '5'},
       {'description': 'understanding of complexities and trade-offs',
        'label': 'Deadlines',
        'score': '5'},
       {'description': 'communication skills and responsiveness, feedback and guidance',
        'label': 'Communication',
        'score': '5'},
       {'description': 'cooperation and flexibility, open to suggestions for improvement',
        'label': 'Cooperation',
        'score': '5'}]}}}]},
 'buyer': {'op_adjusted_score': '5',
  'op_city': 'Bangkok',
  'op_contract_date': 'August 25, 2013',
  'op_country': 'Thailand',
  'op_timezone': 'UTC-08:00 Pacific Time (US & Canada); Los Angeles',
  'op_tot_asgs': '2',
  'op_tot_charge': '1.11',
  'op_tot_fp_asgs': '2',
  'op_tot_hours': '0',
  'op_tot_jobs_filled': '2',
  'op_tot_jobs_open': '0',
  'op_tot_jobs_posted': '5'},
 'candidates': '',
 'ciphertext': '~abcdf1234542a395a4',
 'engagement_weeks': '',
 'interviewees_total_active': '0',
 'job_category_level_one': 'Web, Mobile & Software Dev',
 'job_category_level_two': 'Web Development',
 'job_type': 'Fixed',
 'op_attached_doc': '',
 'op_cny_upm_verified': '1',
 'op_contractor_tier': '',
 'op_ctime': '1377423220000',
 'op_description': 'Will be discussed.',
 'op_engagement': 'Full-time - 30+ hrs/week',
 'op_high_hourly_rate_all': '0',
 'op_low_hourly_rate_all': '0',
 'op_other_jobs': '',
 'op_pref_english_skill': '0',
 'op_pref_fb_score': '0',
 'op_pref_has_portfolio': '0',
 'op_pref_hourly_rate_max': '',
 'op_pref_hourly_rate_min': '',
 'op_pref_location': '',
 'op_pref_odesk_hours': '0',
 'op_required_skills': '',
 'op_title': 'Test Upwork API',
 'op_tot_cand': '0',
 'op_tot_feedback': '1',
 'op_pref_group_id': 'somegroup',
 'op_pref_group_name': 'Super group',
 'op_pref_group_logo': 'http://...',
 'ui_opening_status': 'Closed'}

Invite freelancer to an interview

Returns

If successful, this resource returns a 200 OK message.

DEFINITION
client.hr_v1.invite_to_interview(
    job_id, cover, profile_key=None,
    provider_reference=None)
$interviews->invite( string $jobKey, array $params );
interviews.invite(job_key, params)
interviews.invite(
  String jobKey,
  java.util.HashMap<String,String> params);
interviews.invite(jobKey, params, callback);
$interviews->invite($job_key, %params);
interviews.Invite(jobKey, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
job_ref = '~aaabb99900'
client.hr_v1.invite_to_interview(job_ref, 'Please accept this interview', profile_key='~abcdf12345')
$interviews = new \Upwork\API\Routers\Hr\Interviews($client);
$params = array(
  "profile_key" => "~abcdf12345",
  "cover" => "Please accept this interview"
);
$jobKey = "~aaabb99900";
$interviews->invite($jobKey, $params);
interviews = Upwork::Api::Routers::Hr::Interviews.new(client)
params = {
  'profile_key' => '~abcdf12345',
  'cover' => 'Please accept this interview'
}
job_key = '~aaabb99900'
interviews.invite(job_key, params)
import com.Upwork.api.Routers.Hr.Interviews;
import java.util.HashMap;

Interviews interviews = new Interviews(client);
String jobKey = "~aaabb99900";
HashMap<String, String> params = new HashMap<String, String>();
params.put("profile_key", "~abcdf12345");
params.put("cover", "Please accept this interview");

interviews.invite(jobKey, params);
var Interviews = require('upwork-api/lib/routers/hr/interviews.js').Interviews;

var interviews = new Interviews(api);
var jobKey = '~aaabb99900';
var params = {
  'profile_key': '~abcdf12345',
  'cover': 'Please accept this interview'
};
interviews.invite(jobKey, params, function(error, data) {
  console.log(data);
});
my $interviews = Upwork::Api::Routers::Hr::Interviews->new($api);
my %params = {
  'profile_key' => '~abcdf12345',
  'cover' => 'Please accept this interview'
};
my $job_key = '~aaabb99900';
$interviews->invite($job_key, %params);
import ( interviewsUpwork "github.com/upwork/golang-upwork/api/routers/hr/interviews" )


interviews := interviewsUpwork.New(client)
jobKey = "~aaabb99900";
params := make(map[string]string)
params["profile_key"] = "~abcdf12345"
params["cover"] = "Please accept this interview"

interviews.Invite(jobKey, params)
EXAMPLE RESPONSE
{'auth_user': {'first_name': 'John',
               'last_name': 'Johnson',
               'timezone': 'Asia/Omsk',
               'timezone_offset': '25200'},
 'code': '200',
 'job_info': {'company_id': ''},
 'message': 'OK',
 'server_time': '1404389611'}

Companies and teams

This section describes resources that allow you to manage companies and teams on Upwork.

List companies

Returns

This resource returns the list of companies that the currently authorized user has access to.

DEFINITION
client.hr.get_companies()
$companies->getList();
companies.get_list()
companies.getList();
companies.getList(callback);
$companies->get_list();
companies.GetList()
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.get_companies()
$companies = new \Upwork\API\Routers\Organization\Companies($client);
$companies->getList();
companies = Upwork::Api::Routers::Organization::Companies.new(client)
companies.get_list()
import com.Upwork.api.Routers.Organization.Companies;

Companies companies = new Companies(client);
companies.getList();
var Companies = require('upwork-api/lib/routers/organization/companies.js').Companies;

var companies = new Companies(api);
companies.getList(function(error, data) {
  console.log(data);
});
my $companies = Upwork::Api::Routers::Organization::Companies->new($api);
$companies->get_list();
import ( companiesUpwork "github.com/upwork/golang-upwork/api/routers/organization/companies" )

companies := companiesUpwork.New(client)
companies.GetList()
EXAMPLE RESPONSE
[
  {'name': 'A Test Company',
   'owner_ciphertext': '~~abcdf12345',
   'payment_verification_status': 'VERIFIED',
   'reference': '12345'
  },
  {
    # Another team
  },
  # ...
]

Get company

Returns

This resource returns the details of the referenced company. If a user does not have access to the company, the resource returns a 403 error. This resource does not return the list of teams within the company.

DEFINITION
client.hr.get_company(company_reference)
$companies->getSpecific( integer $cmpReference );
companies.get_specific(company_reference)
companies.getSpecific(String cmpReference);
companies.getSpecific(cmpReference, callback);
$companies->get_specific($company_reference);
companies.GetSpecific(cmpReference)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.get_company(12345)
$companies = new \Upwork\API\Routers\Organization\Companies($client);
$companies->getSpecific(12345);
companies = Upwork::Api::Routers::Organization::Companies.new(client)
companies.get_specific(12345)
import com.Upwork.api.Routers.Organization.Companies;

Companies companies = new Companies(client);
companies.getSpecific("12345");
var Companies = require('upwork-api/lib/routers/organization/companies.js').Companies;

var companies = new Companies(api);
companies.getSpecific('12345', function(error, data) {
  console.log(data);
});
my $companies = Upwork::Api::Routers::Organization::Companies->new($api);
$companies->get_specific(12345);
import ( companiesUpwork "github.com/upwork/golang-upwork/api/routers/organization/companies" )

companies := companiesUpwork.New(client)
companies.GetSpecific("12345")
EXAMPLE RESPONSE
{'name': 'A Test Company',
 'owner_ciphertext': '~~abcdf12345',
 'payment_verification_status': 'VERIFIED',
 'reference': '12345'}

List teams in company

Returns

This resource returns the list of teams in the referenced company.

DEFINITION
client.hr.get_company_teams(company_referece)
$companies->getTeams( integer $cmpReference );
companies.get_teams(company_reference)
companies.getTeams(String cmpReference);
companies.getTeams(cmpReference, callback);
$companies->get_teams($company_reference);
companies.GetTeams(cmpReference)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.get_company_teams(12345)
$companies = new \Upwork\API\Routers\Organization\Companies($client);
$companies->getTeams(12345);
companies = Upwork::Api::Routers::Organization::Companies.new(client)
companies.get_teams(12345)
import com.Upwork.api.Routers.Organization.Companies;

Companies companies = new Companies(client);
companies.getTeams("12345");
var Companies = require('upwork-api/lib/routers/organization/companies.js').Companies;

var companies = new Companies(api);
companies.getTeams('12345', function(error, data) {
  console.log(data);
});
my $companies = Upwork::Api::Routers::Organization::Companies->new($api);
$companies->get_teams(12345);
import ( companiesUpwork "github.com/upwork/golang-upwork/api/routers/organization/companies" )

companies := companiesUpwork.New(client)
companies.GetTeams("12345")
EXAMPLE RESPONSE
[
  {'company__reference': '377329',
   'company_name': 'A Test Company',
   'id': 'abcdfghijk',
   'name': 'A Test Company',
   'parent_team__id': 'abcdfghijk',
   'parent_team__name': 'A Test Company',
   'parent_team__reference': '12345',
   'payment_verification_status': 'VERIFIED',
   'reference': '12345'
  },
  {
    # Another team
  },
  # ...
]

List users in company

Returns

This resource returns the list of users within the referenced company.

DEFINITION
client.hr.get_company_users(company_referece, active=True)
$companies->getUsers( integer $cmpReference );
companies.get_users(company_reference)
companies.getUsers(String cmpReference);
companies.getUsers(cmpReference, callback);
$companies->get_users($company_reference);
companies.GetUsers(cmpReference)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.get_company_users(12345)
$companies = new \Upwork\API\Routers\Organization\Companies($client);
$companies->getUsers(12345);
companies = Upwork::Api::Routers::Organization::Companies.new(client)
companies.get_users(12345)
import com.Upwork.api.Routers.Organization.Companies;

Companies companies = new Companies(client);
companies.getUsers("12345");
var Companies = require('upwork-api/lib/routers/organization/companies.js').Companies;

var companies = new Companies(api);
companies.getUsers('12345', function(error, data) {
  console.log(data);
});
my $companies = Upwork::Api::Routers::Organization::Companies->new($api);
$companies.get_users(12345);
import ( companiesUpwork "github.com/upwork/golang-upwork/api/routers/organization/companies" )

companies := companiesUpwork.New(client)
companies.GetUsers("12345")
EXAMPLE RESPONSE
[
  {
    'first_name': 'John',
    'has_contract': '0',
    'id': 'john_johnson',
    'is_provider': '1',
    'last_name': 'Johnson',
    'public_url': 'https://...',
    'reference': '12345',
    'status': 'active',
    'timezone_offset': '25200'
  },
  {
    # Another teammate
  },
  # ...
]

List teams

Returns

This resource returns the list of all teams that the currently authorized user has access to.

DEFINITION
client.hr.get_teams()
$teams->getList();
teams.get_list()
teams.getList();
teams.getList(callback);
$teams->get_list();
teams.GetList()
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.get_teams()
$teams = new \Upwork\API\Routers\Organization\Teams($client);
$teams->getList();
teams = Upwork::Api::Routers::Organization::Teams.new(client)
teams.get_list()
import com.Upwork.api.Routers.Organization.Teams;

Teams teams = new Teams(client);
teams.getList();
var Teams = require('upwork-api/lib/routers/organization/teams.js').Teams;

var teams = new Teams(api);
teams.getList(function(error, data) {
  console.log(data);
});
my $teams = Upwork::Api::Routers::Organization::Teams->new($api);
$teams.get_list();
import ( teamsUpwork "github.com/upwork/golang-upwork/api/routers/organization/teams" )

teams := teamsUpwork.New(client)
teams.GetList()
EXAMPLE RESPONSE
[
  {
    'company__reference': '12345',
    'company_name': 'A Test Company',
    'id': 'abcdfghijk',
    'name': 'A Test Team',
    'parent_team__id': 'abcdfghijk',
    'parent_team__name': 'A Test Company',
    'parent_team__reference': '12345',
    'reference': '12345'
   },
   {
     # Another team
   },
   # ...
 ]

List users in team

Returns

This resource returns the following details of all the users in the referenced team:

reference
Reference ID of the team.

status

timezone_offset
The user’s timezone.
id
The user ID.
is_provider
Indicates whether a user is a freelancer. The value 1 means “yes” and 0 means “no”.
last_name
The user’s last name.
first_name
The user’s first name.
DEFINITION
client.hr.get_team_users(team_reference, active=True)
$teams->getUsersInTeam( integer $teamReference );
teams.get_users_in_team(team_reference)
teams.getUsersInTeam(String teamReference);
teams.getUsersInTeam(teamReference, callback);
$teams->get_users_in_team($team_reference);
teams.GetUsersInTeam(teamReference)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.get_team_users(12345)
$teams = new \Upwork\API\Routers\Organization\Teams($client);
$teams->getUsersInTeam(12345);
teams = Upwork::Api::Routers::Organization::Teams.new(client)
teams.get_users_in_team(12345)
import com.Upwork.api.Routers.Organization.Teams;

Teams teams = new Teams(client);
teams.getUsersInTeam("12345");
var Teams = require('upwork-api/lib/routers/organization/teams.js').Teams;

var teams = new Teams(api);
teams.getUsersInTeam('12345', function(error, data) {
  console.log(data);
});
my $teams = Upwork::Api::Routers::Organization::Teams->new($api);
$teams->get_users_in_team(12345);
import ( teamsUpwork "github.com/upwork/golang-upwork/api/routers/organization/teams" )

teams := teamsUpwork.New(client)
teams.GetUsersInTeam("12345")
EXAMPLE RESPONSE
[
  {
    'first_name': 'John',
    'has_contract': '0',
    'id': 'john_johnson',
    'is_provider': '1',
    'last_name': 'Johnson',
    'public_url': 'https://...',
    'reference': '12345',
    'status': 'active',
    'timezone_offset': '25200'
  },
  {
    # Another teammate
  },
  # ...
]

List team rooms

Returns

This resource returns the following details of the teams accessible to the currently authenticated user:

teamrooms
A container for team rooms.
teamroom
A container for team room items.
company_recno
A unique ID number of the current company.
company_name
The name of the current team company.
name
The name of the current team.
id
The ID name of the current team.
recno
A unique ID number of the current team.
teamroom_api
The current teamroom resource.
DEFINITION
client.team_v2.get_teamrooms()
$teams->getList();
teams.get_list()
teams.getList();
teams.getList(callback);
$teams->get_list();
teams.GetList()
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.team_v2.get_teamrooms()
$teams = new \Upwork\API\Routers\Teams($client);
$teams->getList();
teams = Upwork::Api::Routers::Teams.new(client)
teams.get_list()
import com.Upwork.api.Routers.Teams;

Teams teams = new Teams(client);
teams.getList();
var Teams = require('upwork-api/lib/routers/teams.js').Teams;

var teams = new Teams(api);
teams.getList(function(error, data) {
  console.log(data);
});
my $teams = Upwork::Api::Routers::Teams->new($api);
$teams->get_list();
import ( teamsUpwork "github.com/upwork/golang-upwork/api/routers/teams" )

teams := teamsUpwork.New(client)
teams.GetList()
EXAMPLE RESPONSE
[
  {
    'company_name': 'A Test Company',
    'id': 'abcdefghijk',
    'name': 'A Test Team',
    'parent_team_ref': '12345',
    'team_ref': '12345',
    'teamroom_api': '/api/team/v2/teamrooms/abcdefghijk.json'
  },
  {
    # Another teamroom
  },
  # ...
]

Get team room

Returns

This resource returns the following details of the snapshots:

Snapshot
This snapshot response is unique to the resource called. In this case, it refers to the team responses when using the team resource.
status
The current status of the snapshot.
time
Timestamp of the current snapshot taken.
billing_status
The current status of the user, billed or active.
report_url
URL linking to a detailed report of the user’s activity.
activity
The level of the user’s activity, on a scale of 0 (low) to 10 (high).
last_worked_status
The date time when a user last worked. If the user is online, the time is now.
memo
Current user memo as entered into the Upwork team client.
DEFINITION
client.get_snapshots(
    company_or_team_id, online=None, disabled=None)
$teams->getSpecific( string $team, array $params = array() );
teams.get_specific(team, params)
teams.getSpecific(
  String team,
  java.util.HashMap<String,String> params);
teams.getSpecific(team, params, callback);
$teams->get_specific($team, %params);
teams.GetSpecific(team, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.get_snapshots('abcdf12345')
$teams = new \Upwork\API\Routers\Teams($client);
$teams->getSpecific("abcdf12345");
teams = Upwork::Api::Routers::Teams.new(client)
teams.get_specific("abcdf12345", {})
import com.Upwork.api.Routers.Organization.Teams;
import java.util.HashMap;

Teams teams = new Teams(client);
HashMap<String, String> params = new HashMap<String, String>();

teams.getSpecific("abcdf12345", params);
var Teams = require('upwork-api/lib/routers/teams.js').Teams;

var teams = new Teams(api);
var team = 'abcdf12345';
var params = {};
teams.getSpecific(team, params, function(error, data) {
  console.log(data);
});
my $teams = Upwork::Api::Routers::Teams->new($api);
$teams->get_specific("abcdf12345", {});
import ( teamsUpwork "github.com/upwork/golang-upwork/api/routers/organization/teams" )


teams := teamsUpwork.New(client)
params := make(map[string]string)

teams.GetSpecific("abcdf12345", params)
EXAMPLE RESPONSE
[
  {
    'account_status': 'enabled',
    'active_window_title': 'Upwork Team Client',
    'activity': '5',
    'billing_status': 'billed.active',
    'cellts': '1404472378',
    'client_version': '',
    'company_id': 'abcdf12345',
    'computer_name': '',
    'digest': '',
    'keyboard_events_count': '223',
    'last_worked': '1404472378',
    'last_worked_snapshot_api': '/api/team/v1/snapshots...',
    'last_worked_status': 'now',
    'memo': 'New Upwork Public API documentation',
    'mouse_events_count': '0',
    'online_presence': '13,6,6,0,26,73,33,20',
    'online_presence_img': 'https://...',
    'portrait_50_img': 'https://...',
    'portrait_img': 'https://...',
    'profile_url': 'https://...',
    'report24_img': 'https://...',
    'report_url': 'https://...',
    'role': 'contractor',
    'screenshot_img': 'https://...',
    'screenshot_img_lrg': 'https://...',
    'screenshot_img_med': 'https://...',
    'screenshot_img_thmb': 'https://...',
    'screenshot_url': 'https://...',
    'snapshot_api': '/api/team/v1/snapshots...',
    'status': 'NORMAL',
    'time': '1404472378',
    'timezone': 'UTC+07:00 Bangkok, Jakarta, Hanoi',
    'uid': '',
    'user': {'archiving_time': '1404086400',
    'creation_time': '1376941475',
    'first_name': 'John',
    'last_name': 'Johnson',
    'mail': 'john_johnson@example.com',
    'messenger_id': '',
    'messenger_type': '',
    'timezone': 'Asia/Bangkok',
    'timezone_offset': '25200',
    'uid': 'john_johnson'},
    'user_id': 'john_johnson',
    'view_assignment_url': 'https://...',
    'workdiary_api': '/api/team/v1/workdiaries...'}]

Get Work Diary

Returns

This resource returns the following details of the snapshots:

user
The user of the Work diary.
timezone
The time zone of the current authenticated user.
uid
The user ID of the current authenticated user.
timezone_offset
The difference between current time and GMT.
creation_time
Time when the current Work diary entry was created. Format: UNIX timestamp.
mail
The default mail ID of the current authenticated user.
last_name
The user’s last name.
first_name
The user’s first name.
snapshot
The snapshot details.
cell_time
The time when the snapshot was captured.
allow_edit
Defines if the current entry is editable or not.
status
The status of the current entry.
time
The timestamp of the current entry.
billing_status
Billing status.
screenshot_img
URL to the screenshot of the Work diary image.
activity
The level of the user’s activity; on a scale of 0 (low) to 10 (high).
screenshot_url
The URL of the screenshot for this entry.
mouse_events_count
The number of mouse events associated with this entry.
company_id
The Upwork ID of the company associated with the user in this entry.
timezone
The time zone of the entry.
uid
The user ID of the user.
keyboard_events_count
The number of keyboard events associated with this entry.
memo
The memo associated with the current entry.
active_window_title
The name of the active window at the user’s device when the entry was made.
computer_name
The name of the user’s device during the current entry.
screenshot_img_thmb
URL of a thumbnail of the current screenshot.
user_id
The user’s Upwork ID.
client_version
The client version used.
snapshot_api
The resource used for the snapshot.
DEFINITION
client.team.get_workdiaries(
    team_id, username, date=None, tz=None)
$workdiary->get( string $company, string $username, string $date, string $params = array() );
workdiary.get(company, username, date, params = {})
workdiary.get(
  String company,
  String username,
  String date,
  java.util.HashMap<String,String> params);
workdiary.get(
  company, username, date,
  params, callback);
$workdiary->get($company, $username, $date, %params);
workdiary.Get(company, username, date, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.team.get_workdiaries('abcde12345', 'john_johnson', date='20140704')
$workdiary = new \Upwork\API\Routers\Workdiary($client);
$workdiary->get("abcde12345", "john_johnson", "20140704");
workdiary = Upwork::Api::Routers::Workdiary.new(client)
workdiary.get('abcde12345', 'john_johnson', '20140704')
import com.Upwork.api.Routers.Workdiary;
import java.util.HashMap;

Workdiary workdiary = new Workdiary(client);
HashMap<String, String> params = new HashMap<String, String>();

workdiary.get("abcde12345", "john_johnson", "20140704", params);
var Workdiary = require('upwork-api/lib/routers/workdiary.js').Workdiary;

var workdiary = new Workdiary(api);
var params = {};
workdiary.get('abcde12345', 'john_johnson', '20140704', params, function(error, data) {
  console.log(data);
});
my $workdiary = Upwork::Api::Routers::Workdiary->new($api);
$workdiary->get('abcde12345', 'john_johnson', '20140704');
import ( workdiaryUpwork "github.com/upwork/golang-upwork/api/routers/workdiary" )


workdiary := workdiaryUpwork.New(client)
params := make(map[string]string)

workdiary.Get("abcde12345", "john_johnson", "20140704", params)
EXAMPLE RESPONSE
(
  {
    'archiving_time': '1404691200',
    'creation_time': '1376941475',
    'first_name': 'John',
    'last_name': 'Johnson',
    'mail': 'john_johnson@example.com',
    'status': 'enabled',
    'timezone': 'Asia/Bangkok',
    'timezone_offset': '25200',
    'uid': 'john_johnson'
  },
  [
    {
      'account_status': '',
      'active_window_title': 'emacs@user-laptop',
      'activity': '2',
      'allow_delete': 'true',
      'allow_edit': 'true',
      'billing_status': 'billed.active',
      'cell_time': '1404735600',
      'cellts': '',
      'client_version': 'Linux/3.12.9',
      'company_id': 'abcdef12345',
      'computer_name': 'user-laptop',
      'digest': '',
      'keyboard_events_count': '142',
      'memo': 'New Upwork Public API documentation',
      'mouse_events_count': '33',
      'screenshot_img': 'https://...',
      'screenshot_img_lrg': 'https://...',
      'screenshot_img_med': 'https://...',
      'screenshot_img_thmb': 'https://...',
      'screenshot_url': 'https://...',
      'snapshot_api': '/api/team/v1/snapshots/...',
      'status': 'NORMAL',
      'time': '1404736072',
      'timezone': '',
      'uid': 'abcdff38-9999-4444-9999-adcdfegihgklm',
      'user_id': 'john_johnson'
    },
    {
      # Another entry
    },
    # ...
  ]
)

Get Work Diary by Contract

Returns

This resource returns the following details of the snapshots:

user
The user of the Work diary.
timezone
The time zone of the current authenticated user.
uid
The user ID of the current authenticated user.
timezone_offset
The difference between current time and GMT.
creation_time
Time when the current Work diary entry was created. Format: UNIX timestamp.
mail
The default mail ID of the current authenticated user.
last_name
The user’s last name.
first_name
The user’s first name.
snapshot
The snapshot details.
cell_time
The time when the snapshot was captured.
allow_edit
Defines if the current entry is editable or not.
status
The status of the current entry.
time
The timestamp of the current entry.
billing_status
Billing status.
screenshot_img
URL to the screenshot of the Work diary image.
activity
The level of the user’s activity; on a scale of 0 (low) to 10 (high).
screenshot_url
The URL of the screenshot for this entry.
mouse_events_count
The number of mouse events associated with this entry.
company_id
The Upwork ID of the company associated with the user in this entry.
timezone
The time zone of the entry.
uid
The user ID of the user.
keyboard_events_count
The number of keyboard events associated with this entry.
memo
The memo associated with the current entry.
active_window_title
The name of the active window at the user’s device when the entry was made.
computer_name
The name of the user’s device during the current entry.
screenshot_img_thmb
URL of a thumbnail of the current screenshot.
user_id
The user’s Upwork ID.
client_version
The client version used.
snapshot_api
The resource used for the snapshot.
DEFINITION
client.team.get_workdiaries_by_contract(
    contract_id, date=None, tz=None)
$workdiary->getByContract( string $contract_id, string $date, string $params = array() );
workdiary.get_by_contract(contract_id, date, params = {})
workdiary.getByContract(
  String contract_id,
  String date,
  java.util.HashMap<String,String> params);
workdiary.getByContract(
  contract_id, date,
  params, callback);
$workdiary->get_by_contract($contract_id, $date, %params);
workdiary.GetByContract(contract_id, date, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.team.get_workdiaries_by_contract('12345;78912', date='20140704')
$workdiary = new \Upwork\API\Routers\Workdiary($client);
$workdiary->getByContract("12345;78912", "20140704");
workdiary = Upwork::Api::Routers::Workdiary.new(client)
workdiary.get_by_contract('12345;78912', '20140704')
import com.Upwork.api.Routers.Workdiary;
import java.util.HashMap;

Workdiary workdiary = new Workdiary(client);
HashMap<String, String> params = new HashMap<String, String>();

workdiary.getByContract("12345;78912", "20140704", params);
var Workdiary = require('upwork-api/lib/routers/workdiary.js').Workdiary;

var workdiary = new Workdiary(api);
var params = {};
workdiary.getByContract('12345;78912', '20140704', params, function(error, data) {
  console.log(data);
});
my $workdiary = Upwork::Api::Routers::Workdiary->new($api);
$workdiary->get_by_contract('12345;78912', '20140704');
import ( workdiaryUpwork "github.com/upwork/golang-upwork/api/routers/workdiary" )


workdiary := workdiaryUpwork.New(client)
params := make(map[string]string)

workdiary.GetByContract("12345;78912", "20140704", params)
EXAMPLE RESPONSE
(
  {
    'archiving_time': '1404691200',
    'creation_time': '1376941475',
    'first_name': 'John',
    'last_name': 'Johnson',
    'mail': 'john_johnson@example.com',
    'status': 'enabled',
    'timezone': 'Asia/Bangkok',
    'timezone_offset': '25200',
    'uid': 'john_johnson'
  },
  [
    {
      'account_status': '',
      'active_window_title': 'emacs@user-laptop',
      'activity': '2',
      'allow_delete': 'true',
      'allow_edit': 'true',
      'billing_status': 'billed.active',
      'cell_time': '1404735600',
      'cellts': '',
      'client_version': 'Linux/3.12.9',
      'company_id': 'abcdef12345',
      'computer_name': 'user-laptop',
      'digest': '',
      'keyboard_events_count': '142',
      'memo': 'New Upwork Public API documentation',
      'mouse_events_count': '33',
      'screenshot_img': 'https://...',
      'screenshot_img_lrg': 'https://...',
      'screenshot_img_med': 'https://...',
      'screenshot_img_thmb': 'https://...',
      'screenshot_url': 'https://...',
      'snapshot_api': '/api/team/v1/snapshots/...',
      'status': 'NORMAL',
      'time': '1404736072',
      'timezone': '',
      'uid': 'abcdff38-9999-4444-9999-adcdfegihgklm',
      'user_id': 'john_johnson'
    },
    {
      # Another entry
    },
    # ...
  ]
)

Get Workdays by Company

Returns

This resource returns the list of active workdays in the company for the currently authenticated user, and the following details:

range
Specified range.
workday.date
List of workdays.
workday.workdiary_api
The resource used for Workdiary.
DEFINITION
client.team.get_workdays_by_company(
    company_id, date=None, tz=None)
$workdays->getByCompany( string $contract_id, string $from_date, string $till_date, string $params = array() );
workdays.get_by_company(company_id, from_date, till_date, params = {})
workdays.getByCompany(
  String company_id,
  String from_date,
  String till_date,
  java.util.HashMap<String,String> params);
workdays.getByCompany(
  company_id, from_date, till_date,
  params, callback);
$workdays->get_by_company($company_id, $from_date, $till_date, %params);
workdays.GetByCompany(company_id, from_date, till_date, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.team.get_workdays_by_company('testcompany', from_date='20150704', till_date='20150710')
$workdays = new \Upwork\API\Routers\Workdays($client);
$workdays->getByCompany("testcompany", "20150704", "20150710");
workdays = Upwork::Api::Routers::Workdays.new(client)
workdays.get_by_company('testcompany', '20150704', '20150710')
import com.Upwork.api.Routers.Workdays;
import java.util.HashMap;

Workdays workdays = new Workdays(client);
HashMap<String, String> params = new HashMap<String, String>();

workdays.getByCompany("testcompany", "20150704", "20150710" params);
var Workdays = require('upwork-api/lib/routers/workdays.js').Workdays;

var workdays = new Workdays(api);
var params = {};
workdays.getByCompany('testcompany', '20150704', '20150710', params, function(error, data) {
  console.log(data);
});
my $workdays = Upwork::Api::Routers::Workdays->new($api);
$workdays->get_by_company('testcompany', '20150704', '20150710');
import ( workdaysUpwork "github.com/upwork/golang-upwork/api/routers/workdays" )


workdays := workdaysUpwork.New(client)
params := make(map[string]string)

workdays.GetByCompany("testcompany", "20150704", "20150710" params)
EXAMPLE RESPONSE
(
  {
    'archiving_time': '1404691200',
    'creation_time': '1376941475',
    'first_name': 'John',
    'last_name': 'Johnson',
    'mail': 'john_johnson@example.com',
    'status': 'enabled',
    'timezone': 'Asia/Bangkok',
    'timezone_offset': '25200',
    'uid': 'john_johnson'
  },
  'workdays': {
    'range': {
       'to': '1288915200',
       'from': '1281052800'
     },
     'workday': {
       'date': [
         '20100816',
         '20100904'
       ],
       'workdiary_api': '/api/team/v2/workdiaries/companies/testcompany.json'
     }
  }
)

Get Workdays by Contract

Returns

This resource returns the list of active workdays and the following details:

range
Specified range.
workday.date
List of workdays.
workday.workdiary_api
The resource used for Workdiary.
DEFINITION
client.team.get_workdays_by_contract(
    contract_id, date=None, tz=None)
$workdays->getByContract( string $contract_id, string $from_date, string $till_date, string $params = array() );
workdays.get_by_contract(contract_id, from_date, till_date, params = {})
workdays.getByContract(
  String contract_id,
  String from_date,
  String till_date,
  java.util.HashMap<String,String> params);
workdays.getByContract(
  contract_id, from_date, till_date,
  params, callback);
$workdays->get_by_contract($contract_id, $from_date, $till_date, %params);
workdays.GetByContract(contract_id, from_date, till_date, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.team.get_workdays_by_contract('12345', from_date='20150704', till_date='20150710')
$workdays = new \Upwork\API\Routers\Workdays($client);
$workdays->getByContract("12345", "20150704", "20150710");
workdays = Upwork::Api::Routers::Workdays.new(client)
workdays.get_by_contract('12345', '20150704', '20150710')
import com.Upwork.api.Routers.Workdays;
import java.util.HashMap;

Workdays workdays = new Workdays(client);
HashMap<String, String> params = new HashMap<String, String>();

workdays.getByContract("12345", "20150704", "20150710" params);
var Workdays = require('upwork-api/lib/routers/workdays.js').Workdays;

var workdays = new Workdays(api);
var params = {};
workdays.getByContract('12345', '20150704', '20150710', params, function(error, data) {
  console.log(data);
});
my $workdays = Upwork::Api::Routers::Workdays->new($api);
$workdays->get_by_contract('12345', '20150704', '20150710');
import ( workdaysUpwork "github.com/upwork/golang-upwork/api/routers/workdays" )


workdays := workdaysUpwork.New(client)
params := make(map[string]string)

workdays.GetByContract("12345", "20150704", "20150710" params)
EXAMPLE RESPONSE
(
  {
    'archiving_time': '1404691200',
    'creation_time': '1376941475',
    'first_name': 'John',
    'last_name': 'Johnson',
    'mail': 'john_johnson@example.com',
    'status': 'enabled',
    'timezone': 'Asia/Bangkok',
    'timezone_offset': '25200',
    'uid': 'john_johnson'
  },
  'workdays': {
    'range': {
       'to': '1288915200',
       'from': '1281052800'
     },
     'workday': {
       'date': [
         '20100816',
         '20100904'
       ],
       'workdiary_api': '/api/team/v2/workdiaries/contracts/12345.json'
     }
  }
)

Contracts and offers

This section describes resources that allow you to manage contracts and offers. For example, you can send offers, create and close contracts and manage existing engagements.

List client offers

Returns

See “Possible output fields” section.

DEFINITION
client.list_client_offers(
    company_id=None, team__reference=None,
    job__reference=None, status=None, page_offset=None,
    page_size=None)
$offers->getList( array $params );
offers.get_list(params)
offers.getList(
  java.util.HashMap<String,String> params);
offers.getList(params, callback);
$offers.get_list(%params);
offers.GetList(params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.offers.list_client_offers(company_id='12345')
$offers = new \Upwork\API\Routers\Hr\Clients\Offers($client);
$params = array("company_id" => "12345");
$offers->getList($params);
offers = Upwork::Api::Routers::Hr::Clients::Offers.new(client)
params = {'company_id' => '12345'}
offers.get_list(params)
import com.Upwork.api.Routers.Hr.Clients.Offers;
import java.util.HashMap;

Offers offers = new Offers(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("company_id", "12345");

offers.getList(params);
var Offers = require('upwork-api/lib/routers/hr/clients/offers.js').Offers;

var offers = new Offers(api);
var params = {'company_id': '12345'};
offers.getList(params, function(error, data) {
  console.log(data);
});
my $offers = Upwork::Api::Routers::Hr::Clients::Offers->new($api);
my %params = {company_id => '12345'};
$offers->get_list(%params);
import ( offersUpwork "github.com/upwork/golang-upwork/api/routers/hr/clients/offers" )

offers := offersUpwork.New(client)
params := make(map[string]string)
params["company_id"] = "12345"

offers.GetList(params)
EXAMPLE RESPONSE
 {'auth_user': {'first_name': 'John',
                'last_name': 'Johnson',
                'timezone': 'Asia/Omsk',
                'timezone_offset': '25200'},
  'offers': {
    'lister': {'paging': {'count': '20', 'offset': '0'},
               'query': '',
               'sort': '',
               'total_items': ''},
    'offer': [
      {
        'client_org_ref': '55102',
        'client_user_ref': '106975',
       'contractor_org_ref': '',
        'contractor_user_ref': '3',
        'is_visible_to_contractor': '',
        'job_posting_ref': '',
        'last_event_state': 'new',
        'rid': '70727',
        'terms_data': {
          'charge_rate': '21.0',
          'charge_weekly_stipend_amount': '',
          'manual_time_allowed': '',
          'start_date': '1405036800000',
          'type': 'hourly',
          'weekly_limit': ''
        },
        'title': 'Test offers API',
        'type': 'hourly'
      },
      {
        # Another offer object
      },
      # ..
    ]
  },
'server_time': '1405046576'}

Get client offer

Returns

See “Possible output fields” section.

DEFINITION
client.offers.get_client_offer(
    offer_id, company_id=None, job__reference=None)
$offers->getSpecific( integer $reference, array $params = array() );
offers.get_specific(reference, params)
offers.getSpecific(
  String reference,
  java.util.HashMap<String,String> params);
offers.getSpecific(reference, params, callback);
$offers->get_specific($reference, %params);
offers.GetSpecific(reference, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.offers.get_client_offer(12345, job__reference='~012345abcdef')
$offers = new \Upwork\API\Routers\Hr\Clients\Offers($client);
$params = array("job__reference" => "~012345abcdef");
$offers->getSpecific(12345, $params);
offers = Upwork::Api::Routers::Hr::Clients::Offers.new(client)
params = {'job__reference' => '~012345abcdef'}
offers.get_specific(12345, params)
import com.Upwork.api.Routers.Hr.Clients.Offers;
import java.util.HashMap;

Offers offers = new Offers(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("job__reference", "~012345abcdef");

offers.getSpecific("12345", params);
var offers = require('upwork-api/lib/routers/hr/clients/offers.js').Offers;

var Offers = new Offers(api);
var reference = '12345';
var params = {'job__reference': '~012345abcdef'};
offers.getSpecific(reference, params, function(error, data) {
  console.log(data);
});
my $offers = Upwork::Api::Routers::Hr::Clients::Offers->new($api);
my %params = {job__reference => '~012345abcdef'};
$offers->get_specific(12345, %params);
import ( offersUpwork "github.com/upwork/golang-upwork/api/routers/hr/clients/offers" )

offers := offersUpwork.New(client)
params := make(map[string]string)
params["job__reference"] = "~012345abcdef"

offers.GetSpecific("12345", params)
EXAMPLE RESPONSE
{
  'auth_user': {'first_name': 'John',
                'last_name': 'Johnson',
                'timezone': 'Asia/Omsk',
                'timezone_offset': '25200'},
  'offer': {
    'client_org_ref': '12345',
    'client_user_ref': '102345',
    'contractor_org_ref': '',
    'contractor_user_ref': '102345',
    'is_visible_to_contractor': '',
    'job_posting_ref': '',
    'last_event_state': 'new',
    'rid': '77777',
    'terms_data': {
      'charge_rate': '20.0',
      'charge_weekly_stipend_amount': '',
      'start_date': '1404777600000',
      'type': 'hourly',
      'weekly_limit': ''
    },
    'title': 'Test offers API send offer',
    'type': 'hourly'
  },
  'server_time': '1404906002'
}

Send client offer

Returns

If the request is successful, a 200 OK message is returned together with the offer ID.

DEFINITION
client.send_client_offer(
    title, job_type, charge_rate, message_to_contractor,
    team__reference=None, client_team_ref=None,
    contractor_username=None, contractor_reference=None,
    contractor_key=None, contractor_org=None, context=None,
    charge_upfront_percent=None, weekly_limit=None,
    weekly_stipend=None, expires_on=None,
    close_on_accept=None, milestones=None, related_jobcategory2=None)
$offers->makeOffer( array $params );
offers.make_offer(params)
offers.makeOffer(
  java.util.HashMap<String,String> params);
offers.makeOffer(params, callback);
$offers->make_offer(%params);
offers.MakeOffer(params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
milestones = [
    {"milestone_description":"description 1", "deposit_amount":"101", "due_date":"03-15-2015"},
    {"milestone_description":"description 2", "deposit_amount":"102", "due_date":"03-18-2015"}
]
context = {'related_jobcategory2': '531770282589057025'}
client.offers.send_client_offer('Test offers API send offer 02', 'hourly', 20.0, 'Please accept this test job',
     team__reference=12345, client_team_ref='mycompany:testteam', contractor_username='john_freelancer', context=context, milestones=milestones)
$offers = new \Upwork\API\Routers\Hr\Clients\Offers($client);
$params = array(
  "title" => "Test offers API send offer 02",
  "job_type" => "hourly",
  "charge_rate" => "20.0",
  "message_to_contractor" => "Please accept this test job",
  "team__reference" => "12345",
  "contractor_username" => "john_freelancer"
);
$offers->makeOffer($params);
offers = Upwork::Api::Routers::Hr::Clients::Offers.new(client)
params = {
  'title' => 'Test offers API send offer 02',
  'job_type' => 'hourly',
  'charge_rate' => '20.0',
  'message_to_contractor' => 'Please accept this test job',
  'team__reference' => '12345',
  'contractor_username' => 'john_freelancer'
}
offers.make_offer(params)
import com.Upwork.api.Routers.Hr.Clients.Offers;
import java.util.HashMap;

Offers offers = new Offers(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("title", "Test offers API send offer 02");
params.put("job_type", "hourly");
params.put("charge_rate", "20.0");
params.put("message_to_contractor", "Please accept this test job");
params.put("team__reference", "12345");
params.put("contractor_username", "john_freelancer");

offers.makeOffer(params);
var Offers = require('upwork-api/lib/routers/hr/clients/offers.js').Offers;

var offers = new Offers(api);
var params = {
  'title': 'Test offers API send offer 02',
  'job_type': 'hourly',
  'charge_rate': '20.0',
  'message_to_contractor': 'Please accept this test job',
  'team__reference': '12345',
  'contractor_username': 'john_freelancer'
};
offers.makeOffer(params, function(error, data) {
  console.log(data);
});
my $offers = Upwork::Api::Routers::Hr::Clients::Offers->new($api);
my %params = {
  'title' => 'Test offers API send offer 02',
  'job_type' => 'hourly',
  'charge_rate' => '20.0',
  'message_to_contractor' => 'Please accept this test job',
  'team__reference' => '12345',
  'contractor_username' => 'john_freelancer'
};
$offers->make_offer(%params);
import ( offersUpwork "github.com/upwork/golang-upwork/api/routers/hr/clients/offers" )

offers := offersUpwork.New(client)
params := make(map[string]string)
params["title"] = "Test offers API send offer 02"
params["job_type"] = "hourly"
params["charge_rate"] = "20.0"
params["message_to_contractor"] = "Please accept this test job"
params["team__reference"] = "12345"
params["contractor_username"] = "john_freelancer"

offers.MakeOffer(params)
EXAMPLE RESPONSE
{
  'auth_user': {'first_name': 'John',
                'last_name': 'Johnson',
                'timezone': 'Asia/Omsk',
                'timezone_offset': '25200'},
   'offer_id': '12345',
   'server_time': 1404844979
 }

List freelancer’s offers

Returns

See “Possible output fields” section.

DEFINITION
client.offers.list_freelancer_offers(
    status=None, page_offset=None, page_size=None)
$offers->getList( array $params );
offers.get_list(params = {})
offers.getList(
  java.util.HashMap<String,String> params);
offers.getList(params, callback);
$offers->get_list(%params);
offers.GetList(params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.offers.list_freelancer_offers()
$offers = new \Upwork\API\Routers\Hr\Freelancers\Offers($client);
$params = array("status" => "new");
$offers->getList($params);
offers = Upwork::Api::Routers::Hr::Freelancers::Offers.new(client)
params = {'status' => 'new'}
offers.get_list(params)
import com.Upwork.api.Routers.Hr.Freelancers.Offers;
import java.util.HashMap;

Offers offers = new Offers(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("status", "new");

offers.getList(params);
var Offers = require('upwork-api/lib/routers/hr/freelancers/offers.js').Offers;

var offers = new Offers(api);
var params = {'status': 'new'};
offers.getList(params, function(error, data) {
  console.log(data);
});
my $offers = Upwork::Api::Routers::Hr::Freelancers::Offers->new($api);
my %params = {'status' => 'new'};
$offers->get_list(%params);
import ( offersUpwork "github.com/upwork/golang-upwork/api/routers/hr/freelancers/offers" )

offers := offersUpwork.New(client)
params := make(map[string]string)
params["status"] = "new"

offers.GetList(params)
EXAMPLE RESPONSE
{
  'auth_user': {'first_name': 'John',
                'last_name': 'Johnson',
                'timezone': 'Asia/Omsk',
                'timezone_offset': '25200'},
  'offers': {
    'lister': {'paging': {'count': '20', 'offset': '0'},
               'query': '',
               'sort': '',
               'total_items': ''},
    'offer': [
      {
        'client_org_ref': '55102',
        'client_user_ref': '106975',
        'contractor_org_ref': '',
        'contractor_user_ref': '106976',
        'is_visible_to_contractor': '',
        'job_posting_ref': '',
        'last_event_state': 'new',
        'rid': '70449',
        'terms_data': {
          'charge_rate': '20.0',
          'charge_weekly_stipend_amount': '',
          'manual_time_allowed': '',
          'start_date': '1404777600000',
          'type': 'hourly',
          'weekly_limit': ''
        },
        'title': 'Test offers API send offer',
        'type': 'hourly'
      },
      {
        # Another offer object
      },
      # ...
    ]
  },
  'server_time': '1405092898'
}

Get freelancer’s offer

Returns

See “Possible output fields” section.

DEFINITION
client.offers.get_freelancer_offer(offer_id)
$offers->getSpecific( integer $reference );
offers.get_specific(reference)
offers.getSpecific(String reference);
offers.getSpecific(reference, callback);
$offers->get_specific($reference);
offers.GetSpecific(reference)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.offers.get_freelancer_offer('12345')
$offers = new \Upwork\API\Routers\Hr\Freelancers\Offers($client);
$offers->getSpecific(12345);
offers = Upwork::Api::Routers::Hr::Freelancers::Offers.new(client)
offers.get_specific(12345)
import com.Upwork.api.Routers.Hr.Freelancers.Offers;
import java.util.HashMap;

Offers offers = new Offers(client);
offers.getSpecific("12345");
var Offers = require('upwork-api/lib/routers/hr/freelancers/offers.js').Offers;

var offers = new Offers(api);
var reference = '12345';
offers.getSpecific(reference, function(error, data) {
  console.log(data);
});
my $offers = Upwork::Api::Routers::Hr::Freelancers::Offers->new($api);
$offers->get_specific(12345);
import ( offersUpwork "github.com/upwork/golang-upwork/api/routers/hr/freelancers/offers" )

offers := offersUpwork.New(client)
offers.GetSpecific("12345")
EXAMPLE RESPONSE
{'auth_user': {'first_name': 'John',
               'last_name': 'Johnson',
               'timezone': 'Asia/Omsk',
               'timezone_offset': '25200'},
 'offer': {
   'client_org_ref': '55102',
   'client_user_ref': '106975',
   'contractor_org_ref': '',
   'contractor_user_ref': '106976',
   'is_visible_to_contractor': '',
   'job_posting_ref': '',
   'last_event_state': 'new',
   'rid': '12345',
   'terms_data': {
     'charge_rate': '20.0',
     'charge_weekly_stipend_amount': '',
     'manual_time_allowed': '',
     'related_jobcategory2': '',
     'start_date': '1404777600000',
     'type': 'hourly',
     'version': 'v1',
     'weekly_limit': ''
   },
   'title': 'Test offers API resource sends an offer',
   'type': 'hourly'
 },
 'server_time': '1405101130'}

Accept or decline an offer

Returns

This resource returns the following response message:

message
Result message.
DEFINITION
client.offers.accept_or_decline(offer_id, action_name)
$offers->actions( array $params );
offers.actions(params = {})
offers.actions(
  java.util.HashMap<String,String> params);
offers.actions(params, callback);
$offers->actions(%params);
offers.Actions(params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
offer_id = '12345'
client.offers.accept_or_decline(offer_id, action_name)
$offers = new \Upwork\API\Routers\Hr\Freelancers\Offers($client);
$params = array("name" => "accept");
$offerId = "12345";
$offers->actions($offerId, $params);
offers = Upwork::Api::Routers::Hr::Freelancers::Offers.new(client)
offer_id = '12345'
params = {'name' => 'accept'}
offers.actions(offer_id, params)
import com.Upwork.api.Routers.Hr.Freelancers.Offers;
import java.util.HashMap;

Offers offers = new Offers(client);
String offerId = "12345";
HashMap<String, String> params = new HashMap<String, String>();
params.put("name", "accept");

offers.actions(offerId, params);
var Offers = require('upwork-api/lib/routers/hr/freelancers/offers.js').Offers;

var offers = new Offers(api);
var offerId = '12345';
var params = {'name': 'accept'};
offers.actions(offerId, params, function(error, data) {
  console.log(data);
});
my $offers = Upwork::Api::Routers::Hr::Freelancers::Offers->new($api);
my $offer_id = '12345';
%params = {'name' => 'accept'};
$offers->actions($offer_id, %params);
import ( offersUpwork "github.com/upwork/golang-upwork/api/routers/hr/freelancers/offers" )

offers := offersUpwork.New(client)
offerId = "12345";
params := make(map[string]string)
params["name"] = "accept"

offers.Actions(offerId, params)
EXAMPLE RESPONSE
{
  'auth_user': {'first_name': 'John',
                'last_name': 'Johnson',
                'timezone': 'Asia/Omsk',
                'timezone_offset': '25200'},
  'message': 'Offer 12345 accepted',
  'server_time': '1405092898'
}

List job applications as client

Returns

See “Possible output fields” section.

DEFINITION
client.hr_v4.list_client_applications(
    buyer_team__reference, job_key, status=None,
    profile_key=None, agency_team__reference=None,
    order_by=None, page_offset=None, page_size=None)
$applications->getList( array $params );
applications.get_list(params)
applications.getList(
  java.util.HashMap<String,String> params);
applications.getList(params, callback);
$applications->get_list(%params);
applications.GetList(params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr_v3.list_client_applications(12345, '~12345abcdef')
$applications = new \Upwork\API\Routers\Hr\Clients\Applications($client);
$params = array(
  "buyer_team__reference" => 12345,
  "job_key" => "~12345abcdef"
);
$applications->getList($params);
applications = Upwork::Api::Routers::Hr::Clients::Applications.new(client)
params = {
  'buyer_team__reference' => 12345,
  'job_key' => '~12345abcdef'
}
applications.get_list(params)
import com.Upwork.api.Routers.Hr.Clients.Applications;
import java.util.HashMap;

Applications applications = new Applications(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("buyer_team__reference", 12345);
params.put("job_key", "~12345abcdef");

applications.getList(params);
var Applications = require('upwork-api/lib/routers/hr/clients/applications.js').Applications;

var applications = new Applications(api);
var params = {
  'buyer_team__reference': 12345,
  'job_key': '~12345abcdef'
};
applications.getList(params, function(error, data) {
  console.log(data);
});
my $applications = Upwork::Api::Routers::Hr::Clients::Applications->new($api);
my %params = {
  'buyer_team__reference' => 12345,
  'job_key' => '~12345abcdef'
};
$applications->get_list(%params);
import ( applicationsUpwork "github.com/upwork/golang-upwork/api/routers/hr/clients/applications" )

applications := applicationsUpwork.New(client)
params := make(map[string]string)
params.Put("buyer_team__reference", 12345)
params["job_key"] = "~12345abcdef"

applications.GetList(params)
EXAMPLE RESPONSE
{
  'applications': [
    {
      'contractor_ciphertext': '~012345abcdef',
      'contractor_name': 'John Johnson',
      'contractor_portrait_url': 'https://...',
      'contractor_ref': '675604',
      'contractor_title': 'Software developer - test WEBAPI oAuth',
      'cover_letter': '',
      'created_type': 'Client',
      'ctime_epoch': '1404794618',
      'engagement_duration_ref': '2',
      'feedback_score': '0',
      'fp_amount_agreed': '',
      'fp_pay_amount': '0',
      'fp_upfront_payment': '0',
      'hr_charge_rate': '22.22',
      'hr_pay_rate': '20',
      'interview_status': 'Waiting For Provider',
      'invite_letter': 'Test invite to interview via oAuth',
      'is_auto_hidden': 'f',
      'is_hidden_by_buyer': '0',
      'is_hidden_by_provider': '0',
      'is_seen_by_buyer': 't',
      'is_shortlisted': '0',
      'is_undecided': '1',
      'job__description': 'Create job via oAuth api',
      'job_pref_matches': {'prefs_match': '0', 'prefs_total': '0'},
      'job_type': 'Hourly',
      'offer_status': '',
      'opening_ciphertext': '~012345abcdef',
      'rid': '12345',
      'status': 'In Process',
      'team_nid': 'unazcm8kj7ytdrwwgc-pkq',
      'total_hours': '0',
      'ui_opening_title': 'Test oAuth API create job'
    }
  ],
  'auth_user': {'first_name': 'John',
                'last_name': 'Johnson',
                'timezone': 'Asia/Omsk',
                'timezone_offset': '25200'},
  'lister': {'paging': {'count': '10', 'offset': '0'},
             'query': '',
             'sort': '',
             'total-count': '1',
             'total_items': ''},
  'server_time': '1405339447'
}

Get job application as client

Returns

See “Possible output fields” section.

DEFINITION
client.hr_v4.get_client_application(
    application_id, buyer_team__reference)
$applications->getSpecific( integer $reference, array $params );
applications.get_specific(reference, params)
applications.getSpecific(
  String reference,
  java.util.HashMap<String,String> params);
applications.getSpecific(reference, params);
$applications->get_specific($reference, %params);
applications.GetSpecific(reference, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr_v3.get_client_application(12345, 67890)
$applications = new \Upwork\API\Routers\Hr\Clients\Applications($client);
$params = array("buyer_team__reference" => 67890);
$applications->getSpecific(12345, $params);
applications = Upwork::Api::Routers::Hr::Clients::Applications.new(client)
params = {'buyer_team__reference' => 67890}
applications.get_specific(12345, params)
import com.Upwork.api.Routers.Hr.Clients.Applications;
import java.util.HashMap;

Applications applications = new Applications(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("buyer_team__reference", "67890");

applications.getSpecific("12345", params);
var Applications = require('upwork-api/lib/routers/hr/clients/applications.js').Applications;

var applications = new Applications(api);
var params = {'buyer_team__reference': 67890};
applications.getSpecific('12345', params, function(error, data) {
  console.log(data);
});
my $applications = Upwork::Api::Routers::Hr::Clients::Applications->new($api);
my %params = {'buyer_team__reference' => 67890};
$applications->get_specific(12345, %params);
import ( applicationsUpwork "github.com/upwork/golang-upwork/api/routers/hr/clients/applications" )

applications := applicationsUpwork.New(client)
params := make(map[string]string)
params["buyer_team__reference"] = "67890"

applications.GetSpecific("12345", params)
EXAMPLE RESPONSE
{
  'application': {
    'contractor_ciphertext': '~012345abcdef',
    'contractor_name': 'John Johnson',
    'contractor_portrait_url': 'https://...',
    'contractor_ref': '675604',
    'contractor_title': 'Software developer - test WEBAPI oAuth',
    'cover_letter': '',
    'created_type': 'Client',
    'ctime_epoch': '1404794618',
    'engagement_duration_ref': '2',
    'feedback_score': '0',
    'fp_amount_agreed': '',
    'fp_pay_amount': '0',
    'fp_upfront_payment': '0',
    'hr_charge_rate': '22.22',
    'hr_pay_rate': '20',
    'interview_status': 'Waiting For Provider',
    'invite_letter': 'Test invite to interview via oAuth',
    'is_auto_hidden': 'f',
    'is_hidden_by_buyer': '0',
    'is_hidden_by_provider': '0',
    'is_seen_by_buyer': 't',
    'is_shortlisted': '0',
    'is_undecided': '1',
    'job__description': 'Create job via oAuth api',
    'job_pref_matches': {'prefs_match': '0', 'prefs_total': '0'},
    'job_type': 'Hourly',
    'offer_status': '',
    'opening_ciphertext': '~00012345abcde',
    'rid': '12345',
    'status': 'In Process',
    'team_nid': 'unazcm8kj7ytdrwwgc-pkq',
    'total_hours': '0',
    'ui_opening_title': 'Test oAuth API create job'
  },
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'server_time': '1405392072'
}

List job applications as freelancer

Returns

See “Possible output fields” section.

DEFINITION
client.list_freelancer_applications(status=None)
$applications->getList( array $params );
applications.get_list(params = {})
applications.getList(
  java.util.HashMap<String,String> params);
applications.getList(params, callback);
$applications->get_list(%params);
applications.GetList(params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.list_freelancer_applications()
$applications = new \Upwork\API\Routers\Hr\Freelancers\Applications($client);
$applications->getList();
applications = Upwork::Api::Routers::Hr::Freelancers::Applications.new(client)
applications.get_list()
import com.Upwork.api.Routers.Hr.Freelancers.Applications;
import java.util.HashMap;

Applications applications = new Applications(client);
HashMap<String, String> params = new HashMap<String, String>();

applications.getList(params);
var Applications = require('upwork-api/lib/routers/hr/freelancers/applications.js').Applications;

var applications = new Applications(api);
var params = {};
applications.getList(params, function(error, data) {
  console.log(data);
});
my $applications = Upwork::Api::Routers::Hr::Freelancers::Applications->new($api);
$applications->get_list();
import ( applicationsUpwork "github.com/upwork/golang-upwork/api/routers/hr/freelancers/applications" )

applications := applicationsUpwork.New(client)
params := make(map[string]string)

applications.GetList(params)
EXAMPLE RESPONSE
{
  'applications': [
    {
      'contractor_ciphertext': '~012345abcdef',
      'ctime_epoch': '1404794618',
      'interview_status': 'Waiting For Provider',
      'opening_ciphertext': '~012345abcdef',
      'opening_title': 'Test oAuth API create job',
      'rid': '12345',
      'status': 'In Process'
    }
  ],
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'server_time': '1405399432'
}

Get job application as freelancer

Returns

See “Possible output fields” section.

DEFINITION
client.hr_v4.get_freelancer_application(application_id)
$applications->getSpecific( integer $reference );
applications.get_specific(reference)
applications.getSpecific(String reference);
applications.getSpecific(reference, callback);
$applications->get_specific($reference);
applications.GetSpecific(reference)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr_v3.get_freelancer_application(12345)
$applications = new \Upwork\API\Routers\Hr\Freelancers\Applications($client);
$applications->getSpecific(12345);
applications = Upwork::Api::Routers::Hr::Freelancers::Applications.new(client)
applications.get_specific(12345)
import com.Upwork.api.Routers.Hr.Freelancers.Applications;

Applications applications = new Applications(client);
applications.getSpecific("12345");
var Applications = require('upwork-api/lib/routers/hr/freelancers/applications.js').Applications;

var applications = new Applications(api);
applications.getSpecific('12345', function(error, data) {
  console.log(data);
});
my $applications = Upwork::Api::Routers::Hr::Freelancers::Applications->new($api);
$applications->get_specific(12345);
import ( applicationsUpwork "github.com/upwork/golang-upwork/api/routers/hr/freelancers/applications" )

applications := applicationsUpwork.New(client)
applications.GetSpecific("12345")
EXAMPLE RESPONSE
{
  'application': {
    'contractor_ciphertext': '~012345abcdef',
    'contractor_name': 'John Johnson',
    'contractor_portrait_url': 'https://...',
    'contractor_ref': '675604',
    'contractor_title': 'Software developer - test WEBAPI oAuth',
    'cover_letter': '',
    'created_type': 'Client',
    'ctime_epoch': '1404794618',
    'engagement_duration_ref': '2',
    'feedback_score': '0',
    'fp_amount_agreed': '',
    'fp_pay_amount': '0',
    'fp_upfront_payment': '0',
    'hr_charge_rate': '22.22',
    'hr_pay_rate': '20',
    'interview_status': 'Waiting For Provider',
    'invite_letter': 'Test invite to interview via oAuth',
    'is_auto_hidden': 'f',
    'is_hidden_by_buyer': '0',
    'is_hidden_by_provider': '0',
    'is_seen_by_buyer': 't',
    'is_shortlisted': '0',
    'is_undecided': '1',
    'job__description': 'Create job via oAuth api',
    'job_pref_matches': {'prefs_match': '0', 'prefs_total': '0'},
    'job_type': 'Hourly',
    'offer_status': '',
    'opening_ciphertext': '~012345abcdef',
    'rid': '12345',
    'status': 'In Process',
    'team_nid': 'unazcm8kj7ytdrwwgc-pkq',
    'total_hours': '0',
    'ui_opening_title': 'Test oAuth API create job'
  },
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'server_time': '1405399734'
}

List engagements

Returns

See “Possible output fields” section.

DEFINITION
client.hr.get_engagements(
    buyer_team_reference=None, include_sub_teams=None,
    provider_reference=None, profile_key=None,
    job_reference=None, agency_team_reference=None,
    status=None, created_time_from=None,
    created_time_to=None, page_offset=0,
    page_size=20, order_by=None)
$engagements->getList( array $params );
engagements.get_list(params)
engagements.getList(
  java.util.HashMap<String,String> params);
engagements.getList(params, callback);
$engagements->get_list(%params);
engagements.GetList(params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.get_engagements()
$engagements = new \Upwork\API\Routers\Hr\Engagements($client);
$engagements->getList();
engagements = Upwork::Api::Routers::Hr::Engagements.new(client)
engagements.get_list({})
import com.Upwork.api.Routers.Hr.Engagements;
import java.util.HashMap;

Engagements engagements = new Engagements(client);
HashMap<String, String> params = new HashMap<String, String>();

engagements.getList(params);
var Engagements = require('upwork-api/lib/routers/hr/engagements.js').Engagements;

var engagements = new Engagements(api);
var params = {};
engagements.getList(params, function(error, data) {
  console.log(data);
});
my $engagements = Upwork::Api::Routers::Hr::Engagements->new($api);
$engagements->get_list({});
import ( engagementsUpwork "github.com/upwork/golang-upwork/api/routers/hr/engagements" )

engagements := engagementsUpwork.New(client)
params := make(map[string]string)

engagements.GetList(params)
EXAMPLE RESPONSE
{
  'engagement': {
    'buyer_team__id': 'unazcm8kj7ytdrwwgc-pkq',
    'buyer_team__reference': '377329',
    'created_time': '1405434052000',
    'description': '',
    'dev_recno_ciphertext': '~012345abcdef',
    'engagement_end_date': '',
    'engagement_job_type': 'hourly',
    'engagement_start_date': '1405382400000',
    'engagement_title': 'Test offers API send offer',
    'hourly_charge_rate': '20.0',
    'is_paused': '',
    'job__title': 'Test offers API send offer',
    'job_ref_ciphertext': '~012345abcdef',
    'offer__reference': '',
    'portrait_url': 'https://...',
    'provider__id': 'john_freelancer',
    'provider__reference': '675604',
    'provider_team__id': '',
    'provider_team__reference': '',
    'reference': '167747',
    'status': 'active',
    'weekly_hours_limit': '',
    'weekly_salary_pay_amount': '',
    'weekly_stipend_hours': ''
  },
  'lister': {
    'paging': {'count': '20', 'offset': '0'},
    'query': '',
    'sort': {'sort': {'sort': ['created_time', 'asc']}},
    'total_count': '1',
    'total_items': '2'
  }
}

Get engagement

Returns

Returns information about the specified engagement.

DEFINITION
client.hr.get_engagement(engagement_reference)
$engagements->getSpecific( integer $reference );
engagements.get_specific(reference)
engagements.getSpecific(String reference);
engagements.getSpecific(reference, callback);
$engagements->get_specific($reference);
engagements.GetSpecific(reference)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.get_engagement(12345)
$engagements = new \Upwork\API\Routers\Hr\Engagements($client);
$engagements->getSpecific(12345);
engagements = desk::Api::Routers::Hr::Engagements.new(client)
engagements.get_specific(12345)
import com.Upwork.api.Routers.Hr.Engagements;

Engagements engagements = new Engagements(client);
engagements.getSpecific("12345");
var Engagements = require('upwork-api/lib/routers/hr/engagements.js').Engagements;

var engagements = new Engagements(api);
engagements.getSpecific('12345', function(error, data) {
  console.log(data);
});
my $engagements = desk::Api::Routers::Hr::Engagements->new($api);
$engagements->get_specific(12345);
import ( engagementsUpwork "github.com/upwork/golang-upwork/api/routers/hr/engagements" )

engagements := engagementsUpwork.New(client)
engagements.GetSpecific("12345")
EXAMPLE RESPONSE
{
  'buyer_team__id': 'unazcm8kj7ytdrwwgc-pkq',
  'buyer_team__reference': '377329',
  'created_time': '1405434052000',
  'description': '',
  'dev_recno_ciphertext': '~012345abcdef',
  'engagement_end_date': '',
  'engagement_job_type': 'hourly',
  'engagement_start_date': '1405382400000',
  'engagement_title': 'Test offers API send offer',
  'hourly_charge_rate': '20.0',
  'is_paused': '',
  'job__title': 'Test offers API send offer',
  'job_ref_ciphertext': '~01234567aaabbb',
  'offer__reference': '',
  'portrait_url': 'https://...',
  'provider__id': 'john_freelancer',
  'provider__reference': '675604',
  'provider_team__id': '',
  'reference': '167747',
  'status': 'active',
  'weekly_hours_limit': '',
  'weekly_salary_pay_amount': '',
  'weekly_stipend_hours': '',
  'milestones': ''
}

Suspend contract

Returns

If successful, this resource returns a 200 OK message.

DEFINITION
client.hr.suspend_contract(
    contract_reference, message)
$contracts->suspendContract(
  integer $reference, array $params );
contracts.suspend_contract(reference, params)
contracts.suspendContract(
  String reference,
  java.util.HashMap<String,String> params);
contracts.suspendContract(reference, params, callback);
$contracts->suspend_contract($reference, %params);
contracts.SuspendContract(reference, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.suspend_contract(
    12345, 'Suspended the contract')
$contracts = new \Upwork\API\Routers\Hr\Contracts($client);
$params = array(
  "message" => "Suspended the contract"
);
$contracts->suspendContract(12345, $params);
contracts = Upwork::Api::Routers::Hr::Contracts.new(client)
params = {
  'message' => 'Suspended the contract'
}
contracts.suspend_contract(12345, params)
import com.Upwork.api.Routers.Hr.Contracts;
import java.util.HashMap;

Contracts contracts = new Contracts(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("message", "Suspended the contract");

contracts.suspendContract("12345", params);
var Contracts = require('upwork-api/lib/routers/hr/contracts.js').Contracts;

var contracts = new Contracts(api);
var reference = '12345';
var params = {'message': 'Suspended the contract'};
contracts.suspendContract(reference, params, function(error, data) {
  console.log(data);
});
my $contracts = Upwork::Api::Routers::Hr::Contracts->new($api);
my %params = {
  'message' => 'Suspended the contract'
};
$contracts->suspend_contract(12345, %params);
import ( contractsUpwork "github.com/upwork/golang-upwork/api/routers/hr/contracts" )

contracts := contractsUpwork.New(client)
params := make(map[string]string)
params["message"] = "Suspended the contract"

contracts.SuspendContract("12345", params)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'message': 'OK',
  'server_time': 1405516669
}

Restart contract

Returns

If successful, this resource returns a 200 OK message.

DEFINITION
client.hr.restart_contract(
    contract_reference, message)
$contracts->restartContract(
  integer $reference, array $params );
contracts.restart_contract(reference, params)
contracts.restartContract(
  String reference,
  java.util.HashMap<String,String> params);
contracts.restartContract(reference, params, callback);
$contracts->restart_contract($reference, %params);
contracts.RestartContract(reference, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.restart_contract(
    12345, 'Restarting the contract')
$contracts = new \Upwork\API\Routers\Hr\Contracts($client);
$params = array(
  "message" => "Restarting the contract"
);
$contracts->restartContract(12345, $params);
contracts = Upwork::Api::Routers::Hr::Contracts.new(client)
params = {
  'message' => 'Restarting the contract'
}
contracts.restart_contract(12345, params)
import com.Upwork.api.Routers.Hr.Contracts;
import java.util.HashMap;

Contracts contracts = new Contracts(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("message", "Restarting the contract");

contracts.restartContract("12345", params);
var Contracts = require('upwork-api/lib/routers/hr/contracts.js').Contracts;

var contracts = new Contracts(api);
var reference = '12345';
var params = {'message': 'Restarting the contract'};
contracts.restartContract(reference, params, function(error, data) {
  console.log(data);
});
my $contracts = Upwork::Api::Routers::Hr::Contracts->new($api);
my %params = {
  'message' => 'Restarting the contract'
};
$contracts->restart_contract(12345, %params);
import ( contractsUpwork "github.com/upwork/golang-upwork/api/routers/hr/contracts" )

contracts := contractsUpwork.New(client)
params := make(map[string]string)
params["message"] = "Restarting the contract"

contracts.RestartContract("12345", params)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'message': 'OK',
  'server_time': 1405516669
}

End contract

Warning

Currently, Upwork website does not show scores sent in the fb_scores field. We strongly suggest you to use Upwork user interface to provide scores.

Returns

If successful, this resource returns a 200 OK message.

DEFINITION
client.hr.end_contract(
    contract_reference, reason, would_hire_again,
    fb_scores=None, fb_comment=None)
$contracts->endContract( integer $reference, array $params );
contracts.end_contract(reference, params)
contracts.endContract(
  String reference,
  java.util.HashMap<String,String> params);
contracts.endContract(reference, params, callback);
$contracts->end_contract($reference, %params);
contracts.EndContract(reference, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.end_contract(
    12345, 'API_REAS_WORK_NOT_NEEDED', 'yes')
$contracts = new \Upwork\API\Routers\Hr\Contracts($client);
$params = array(
  "reason" => "API_REAS_WORK_NOT_NEEDED"
);
$contracts->endContract(12345, $params);
contracts = Upwork::Api::Routers::Hr::Contracts.new(client)
params = {
  'reason' => 'API_REAS_WORK_NOT_NEEDED'
}
contracts.end_contract(12345, params)
import com.Upwork.api.Routers.Hr.Contracts;
import java.util.HashMap;

Contracts contracts = new Contracts(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("reason", "API_REAS_WORK_NOT_NEEDED");

contracts.endContract("12345", params);
var Contracts = require('upwork-api/lib/routers/hr/contracts.js').Contracts;

var contracts = new Contracts(api);
var reference = '12345';
var params = {'reason': 'API_REAS_WORK_NOT_NEEDED'};
contracts.endContract(reference, params, function(error, data) {
  console.log(data);
});
my $contracts = Upwork::Api::Routers::Hr::Contracts->new($api);
my %params = {
  'reason' => 'API_REAS_WORK_NOT_NEEDED'
};
$contracts->end_contract(12345, %params);
import ( contractsUpwork "github.com/upwork/golang-upwork/api/routers/hr/contracts" )

contracts := contractsUpwork.New(client)
params := make(map[string]string)
params["reason"] = "API_REAS_WORK_NOT_NEEDED"

contracts.EndContract("12345", params)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'message': 'OK',
  'server_time': 1405516669
}

Milestones

Fixed-priced jobs allow splitting the contract into milestones (significant points in the process of the work to be done). Then, clients are charged when a milestone is created, the money is placed into “escrow”, and released when the milestone is completed.

As a client, once you’ve hired a freelancer on a fixed-price contract, you can start adding milestones. Milestones are created in a “not funded” status. You can activate one milestone at a time. Also note, that only milestones with a “not funded” status can be edited or deleted. Once the milestone is active it can only be closed by approving it or ending the contract, which cancels it.

As a freelancer you can submit work to a milestone. This work submission can be either approved or rejected by a client. If the submission is approved, the milestone proceeds to a “paid” status and funds in escrow are released to the freelancer.

Get active milestone

Returns

Returns an object representing the currently active milestone.

DEFINITION
client.hr_v3.get_active_milestone(contract_reference)
$milestones->getActiveMilestone( integer $contractId );
milestones.get_active_milestone(contract_id)
milestones.getActiveMilestone(String contractId);
milestones.getActiveMilestone(contractId, callback);
$milestones->get_active_milestone($contract_id);
milestones.GetActiveMilestone(contractId)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
contract_reference = 1234
client.hr_v3.get_active_milestone(contract_reference)
$milestones = new \Upwork\API\Routers\Hr\Milestones($client);
$contractId = 1234
$milestones->getActiveMilestone($contractId);
milestones = Upwork::Api::Routers::Hr::Milestones.new(client)
contract_id = 1234
milestones.get_active_milestone(contract_id)
import com.Upwork.api.Routers.Hr.Milestones;

Milestones milestones = new Milestones(client);
String contractId = "1234";
milestones.getActiveMilestone(contractId);
var Milestones = require('upwork-api/lib/routers/hr/milestones.js').Milestones;

var milestones = new Milestones(api);
var contractId = 1234;
milestones.getActiveMilestone(contractId, function(error, data) {
  console.log(data);
});
my $milestones = Upwork::Api::Routers::Hr::Milestones->new($api);
my $contract_id = 1234;
$milestones->get_active_milestone($contract_id);
import ( milestonesUpwork "github.com/upwork/golang-upwork/api/routers/hr/milestones" )

milestones := milestonesUpwork.New(client)
contractId = "1234";
milestones.GetActiveMilestone(contractId)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'server_time': 1405516669,
  'milestone': {
    'contract_id': '214794',
    'deposit_amount': '30',
    'description': 'New description of milestone 2',
    'due_date': '2015-01-01 00:00:00',
    'id': '11206'
  }
}

List submissions for a milestone

Returns

Returns a list of submissions’ IDs.

DEFINITION
client.hr_v3.get_milestone_submissions(milestone_id)
$milestones-getSubmissions( integer $milestoneId );
milestones.get_submissions(milestone_id)
milestones.getSubmissions(String milestoneId);
milestones.getSubmissions(milestoneId, callback);
$milestones->get_submissions($milestone_id);
milestones.GetSubmissions(milestoneId)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
milestone_id = 1234
client.hr_v3.get_milestone_submissions(milestone_id)
$milestones = new \Upwork\API\Routers\Hr\Milestones($client);
$milestoneId = 1234;
$milestones->getSubmissions($milestoneId);
milestones = Upwork::Api::Routers::Hr::Milestones.new(client)
milestone_id = 1234
milestones.get_submissions(milestone_id)
import com.Upwork.api.Routers.Hr.Milestones;

Milestones milestones = new Milestones(client);
String milestoneId = "1234";
milestones.getSubmissions(milestoneId);
var Milestones = require('upwork-api/lib/routers/hr/milestones.js').Milestones;

var milestones = new Milestones(api);
var milestoneId = 1234;
milestones.getSubmissions(milestoneId, function(error, data) {
  console.log(data);
});
my $milestones = Upwork::Api::Routers::Hr::Milestones->new($api);
my $milestone_id = 1234;
$milestones->get_submissions($milestone_id);
import ( milestonesUpwork "github.com/upwork/golang-upwork/api/routers/hr/milestones" )

milestones := milestonesUpwork.New(client)
milestoneId = "1234";
milestones.GetSubmissions(milestoneId)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'server_time': 1405516669,
  'submissions': [{u'id': u'3378'}, {u'id': u'3380'}]
}

Create a milestone

Returns

This resource returns the ID of the milestone created.

DEFINITION
client.hr_v3.create_milestone(
    contract_reference, milestone_description,
    deposit_amount, due_date=None)
$milestones->create( array $params );
milestones.create(params)
milestones.create(
  java.util.HashMap<String,String> params);
milestones.create(params, callback);
$milestones->create(%params);
milestones.Create(params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
contractor_ref = 1234
client.hr_v3.create_milestone(
    contractor_ref, 'First milestone', 50, '12-12-2014')
$milestones = new \Upwork\API\Routers\Hr\Milestones($client);
$params = array(
  "contract_reference" => "1234",
  "milestone_description" => "First milestone",
  "deposit_amount" => "50",
  "due_date" => "12-12-2014"
);
$milestones->create($params);
milestones = Upwork::Api::Routers::Hr::Milestones.new(client)
params = {
  'contract_reference' => '1234',
  'milestone_description' => 'First milestone',
  'deposit_amount' => '50',
  'due_date' => '12-12-2014'
}
milestones.create(params)
import com.Upwork.api.Routers.Hr.Milestones;
import java.util.HashMap;

Milestones milestones = new Milestones(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("contract_reference", "1234");
params.put("milestone_description", "First milestone");
params.put("deposit_amount", "50");
params.put("due_date", "12-12-2014");

milestones.create(params);
var Milestones = require('upwork-api/lib/routers/hr/milestones.js').Milestones;

var milestones = new Milestones(api);
var params = {
  'contract_reference': '1234',
  'milestone_description': 'First milestone',
  'deposit_amount': '50',
  'due_date': '12-12-2014'
};
milestones.create(params, function(error, data) {
  console.log(data);
});
my $milestones = Upwork::Api::Routers::Hr::Milestones->new($api);
my %params = {
  'contract_reference' => '1234',
  'milestone_description' => 'First milestone',
  'deposit_amount' => '50',
  'due_date' => '12-12-2014'
};
$milestones->create(%params);
import ( milestonesUpwork "github.com/upwork/golang-upwork/api/routers/hr/milestones" )

milestones := milestonesUpwork.New(client)
params := make(map[string]string)
params["contract_reference"] = "1234"
params["milestone_description"] = "First milestone"
params["deposit_amount"] = "50"
params["due_date"] = "12-12-2014"

milestones.Create(params)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'id': '9974',
  'server_time': 1405516669
}

Edit a milestone

Returns

Returns 200 OK in case of success.

DEFINITION
client.hr_v3.edit_milestone(
  milestone_id, milestone_description=None,
  deposit_amount=None, due_date=None, message=None)
$milestones->edit(
  integer $milestoneId, array $params );
milestones.edit(milestone_id, params)
milestones.edit(
  String milestoneId,
  HashMap<String, String> params);
milestones.edit(milestoneId, params, callback);
$milestones->edit($milestone_id, %params);
milestones.Edit(milestoneId, HashMap<String, String> params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
milestone_id = 1234
client.hr_v3.edit_milestone(
    milestone_id,
    milestone_description='New description',
    deposit_amount=30, due_date='01-01-2015',
    message='Updating the milestone terms')
$milestones = new \Upwork\API\Routers\Hr\Milestones($client);
$milestoneId = 1234;
$params = array(
  "milestone_description" => "New description",
  "deposit_amount" => "30",
  "due_date" => "01-01-2015",
  "message" => "Updating the milestone terms"
);
$milestones->edit($milestoneId, $params);
milestones = Upwork::Api::Routers::Hr::Milestones.new(client)
milestone_id = 1234
params = {
  'milestone_description' => 'New description',
  'deposit_amount' => '30',
  'due_date' => '01-01-2015',
  'message' => 'Updating the milestone terms'
}
milestones.edit(milestone_id, params)
import com.Upwork.api.Routers.Hr.Milestones;
import java.util.HashMap;

Milestones milestones = new Milestones(client);
String milestoneId = "1234";
HashMap<String, String> params = new HashMap<String, String>();
params.put("milestone_description", "New description");
params.put("deposit_amount", "30");
params.put("due_date", "01-01-2015");
params.put("message", "Updating the milestone terms");

milestones.edit(milestoneId, params);
var Milestones = require('upwork-api/lib/routers/hr/milestones.js').Milestones;

var milestones = new Milestones(api);
var milestoneId = 1234;
var params = {
  'milestone_description': 'New description',
  'deposit_amount': '30',
  'due_date': '01-01-2015',
  'message': 'Updating the milestone terms'
};
milestones.edit(milestoneId, params, function(error, data) {
  console.log(data);
});
my $milestones = Upwork::Api::Routers::Hr::Milestones->new($api);
my $milestone_id = 1234;
my %params = {
  'milestone_description' => 'New description',
  'deposit_amount' => '30',
  'due_date' => '01-01-2015',
  'message' => 'Updating the milestone terms'
};
$milestones->edit($milestone_id, %params);
import ( milestonesUpwork "github.com/upwork/golang-upwork/api/routers/hr/milestones" )

milestones := milestonesUpwork.New(client)
milestoneId = "1234";
params := make(map[string]string)
params["milestone_description"] = "New description"
params["deposit_amount"] = "30"
params["due_date"] = "01-01-2015"
params["message"] = "Updating the milestone terms"

milestones.Edit(milestoneId, params)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'message': 'ok',
  'server_time': 1405516669
}

Activate a milestone

Returns

Returns 200 OK in case of success.

DEFINITION
client.hr_v3.activate_milestone(
    milestone_id, message=None)
$milestones->activate(
  integer $milestoneId, array $params );
milestones.activate(milestone_id, params)
milestones.activate(
  String milestoneId,
  HashMap<String, String> params);
milestones.activate(milestoneId, params, callback);
$milestones->activate($milestone_id, %params);
milestones.Activate(milestoneId, HashMap<String, String> params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
milestone_id = 1234
client.hr_v3.activate_milestone(
    milestone_id, 'Activating second milestone')
$milestones = new \Upwork\API\Routers\Hr\Milestones($client);
$milestoneId = 1234;
$params = array(
  "message" => "Activating second milestone"
);
$milestones->activate($milestoneId, $params);
milestones = Upwork::Api::Routers::Hr::Milestones.new(client)
milestone_id = 1234
params = {
  'message' => 'Activating second milestone'
}
milestones.activate(milestone_id, params)
import com.Upwork.api.Routers.Hr.Milestones;
import java.util.HashMap;

Milestones milestones = new Milestones(client);
String milestoneId = "1234";
HashMap<String, String> params = new HashMap<String, String>();
params.put("message", "Activating second milestone");

milestones.activate(milestoneId, params);
var Milestones = require('upwork-api/lib/routers/hr/milestones.js').Milestones;

var milestones = new Milestones(api);
var milestoneId = 1234;
var params = {
  'message': 'Activating second milestone'
};
milestones.activate(milestoneId, params, function(error, data) {
  console.log(data);
});
my milestones = Upwork::Api::Routers::Hr::Milestones->new($api);
my milestone_id = 1234;
my %params = {
  'message' => 'Activating second milestone'
};
$milestones->activate($milestone_id, %params);
import ( milestonesUpwork "github.com/upwork/golang-upwork/api/routers/hr/milestones" )

milestones := milestonesUpwork.New(client)
milestoneId = "1234";
params := make(map[string]string)
params["message"] = "Activating second milestone"

milestones.Activate(milestoneId, params)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'message': 'ok',
  'server_time': 1405516669
}

Approve a milestone

Returns

Returns 200 OK in case of success.

DEFINITION
client.hr_v3.approve_milestone(
    milestone_id, amount=None, bonus=None,
    pay_comments=None, underpayment_reason=None,
    note2contractor=None)
$milestones->approve(
  integer $milestoneId, array $params );
milestones.approve(milestone_id, params)
milestones.approve(
  String milestoneId,
  HashMap<String, String> params);
milestones.approve(milestoneId, params, callback);
$milestones->approve($milestone_id, %params);
milestones.Approve(milestoneId, HashMap<String, String> params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr_v3.approve_milestone(
    milestone_id, amount=10, bonus=5,
    pay_comments='A comment', underpayment_reason='331',
    note2contractor='A note here')
$milestones = new \Upwork\API\Routers\Hr\Milestones($client);
$milestoneId = 1234;
$params = array(
  "amount" => "10",
  "bonus" => "5",
  "pay_comments" => "A comment",
  "underpayment_reason" => "331",
  "note2contractor" => "A note here"
);
$milestones->approve($milestoneId, $params);
milestones = Upwork::Api::Routers::Hr::Milestones.new(client)
milestone_id = 1234
params = {
  'amount' => '10',
  'bonus' => '5',
  'pay_comments' => 'A comment',
  'underpayment_reason' => '331',
  'note2contractor' => 'A note here'
}
milestones.approve(milestone_id, params)
import com.Upwork.api.Routers.Hr.Milestones;
import java.util.HashMap;

Milestones milestones = new Milestones(client);
String milestoneId = "1234";
HashMap<String, String> params = new HashMap<String, String>();
params.put("amount", "10");
params.put("bonus", "5");
params.put("pay_comments", "A comment");
params.put("underpayment_reason", "331");
params.put("note2contractor", "A note here");

milestones.approve(milestoneId, params);
var Milestones = require('upwork-api/lib/routers/hr/milestones.js').Milestones;

var milestones = new Milestones(api);
var milestoneId = 1234;
var params = {
  'amount', '10',
  'bonus', '5',
  'pay_comments', 'A comment',
  'underpayment_reason', '331',
  'note2contractor', 'A note here'
};
milestones.approve(milestoneId, params, function(error, data) {
  console.log(data);
});
my $milestones = Upwork::Api::Routers::Hr::Milestones->new($api);
my $milestone_id = 1234;
my %params = {
  'amount' => '10',
  'bonus' => '5',
  'pay_comments' => 'A comment',
  'underpayment_reason' => '331',
  'note2contractor' => 'A note here'
};
$milestones->approve($milestone_id, %params);
import ( milestonesUpwork "github.com/upwork/golang-upwork/api/routers/hr/milestones" )

milestones := milestonesUpwork.New(client)
milestoneId = "1234";
params := make(map[string]string)
params["amount"] = "10"
params["bonus"] = "5"
params["pay_comments"] = "A comment"
params["underpayment_reason"] = "331"
params["note2contractor"] = "A note here"

milestones.Approve(milestoneId, params)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'message': 'ok',
  'server_time': 1405516669
}

Delete a milestone

Returns

Returns 200 OK in case of success.

DEFINITION
client.hr_v3.delete_milestone(milestone_id)
$milestones->delete( integer $milestoneId );
milestones.delete(milestone_id)
milestones.delete(String milestoneId);
milestones.delete(milestoneId, callback);
$milestones->delete($milestone_id);
milestones.Delete(milestoneId)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
milestone_id = 1234
client.hr_v3.delete_milestone(milestone_id)
$milestones = new \Upwork\API\Routers\Hr\Milestones($client);
$milestoneId = 1234;
$milestones->delete($milestoneId);
milestones = Upwork::Api::Routers::Hr::Milestones.new(client)
milestone_id = 1234
milestones.delete(milestone_id)
import com.Upwork.api.Routers.Hr.Milestones;

Milestones milestones = new Milestones(client);
String milestoneId = "1234";
milestones.delete(milestoneId);
var Milestones = require('upwork-api/lib/routers/hr/milestones.js').Milestones;

var milestones = new Milestones(api);
milestoneId = 1234;
milestones.delete(milestoneId, function(error, data) {
  console.log(data);
});
my $milestones = Upwork::Api::Routers::Hr::Milestones->new($api);
mu $milestone_id = 1234;
$milestones.delete($milestone_id);
import ( milestonesUpwork "github.com/upwork/golang-upwork/api/routers/hr/milestones" )

milestones := milestonesUpwork.New(client)
milestoneId = "1234";
milestones.Delete(milestoneId)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'message': 'ok',
  'server_time': 1405516669
}

Submit work to a milestone

Returns

Returns 200 OK in case of success.

DEFINITION
client.hr_v3.request_submission_approval(
    milestone_id, note2client, amount)
$submissions->requestApproval( array $params );
submissions.request_approval(params)
submissions.requestApproval(
  HashMap<String, String> params);
submissions.requestApproval(params, callback);
$submissions->request_approval(%params);
submissions.RequestApproval(HashMap<String, String> params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
milestone_id = 1234
client.hr_v3.request_submission_approval(
    milestone_id, 'First milestone completed', 15)
$submissions = new \Upwork\API\Routers\Hr\Submissions($client);
$params = array(
  "milestone_id" => "1234",
  "note2client" => "First milestone completed",
  "amount" => "15"
);
$submissions->requestApproval($params);
submissions = Upwork::Api::Routers::Hr::Submissions.new(client)
params = {
  'milestone_id' => '1234',
  'note2client' => 'First milestone completed',
  'amount' => '15'
}
submissions.request_approval(params)
import com.Upwork.api.Routers.Hr.Submissions;
import java.util.HashMap;

Submissions submissions = new Submissions(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("milestone_id", "1234");
params.put("note2client", "First milestone completed");
params.put("amount", "15");

submissions.requestApproval(params);
var Submissions = require('upwork-api/lib/routers/hr/submissions.js').Submissions;

var submissions = new Submissions(api);
var params = {
  'milestone_id': '1234',
  'note2client': 'First milestone completed',
  'amount': '15'
};
submissions.requestApproval(params, function(error, data) {
  console.log(data);
});
my $submissions = Upwork::Api::Routers::Hr::Submissions->new($api);
my %params = {
  'milestone_id' => '1234',
  'note2client' => 'First milestone completed',
  'amount' => '15'
};
$submissions->request_approval(%params);
import ( submissionsUpwork "github.com/upwork/golang-upwork/api/routers/hr/submissions" )

submissions := submissionsUpwork.New(client)
params := make(map[string]string)
params["milestone_id"] = "1234"
params["note2client"] = "First milestone completed"
params["amount"] = "15"

submissions.RequestApproval(params)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'message': 'ok',
  'server_time': 1405516669
}

Approve a milestone submission

Returns

Returns 200 OK in case of success.

DEFINITION
client.hr_v3.approve_submission(
    submission_id, amount, bonus=None,
    pay_comments=None, underpayment_reason=None,
    note2contractor=None)
$submissions->approve(
  integer $submissionId, array $params );
submissions.approve(submission_id, params)
submissions.approve(
  String submissionId,
  HashMap<String, String> params);
submissions.approve(submissionId, params, callback);
$submissions->approve($submission_id, %params);
submissions.Approve(submissionId, HashMap<String, String> params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
submission_id = 1234
client.hr_v3.approve_submission(
    submission_id, 10, bonus=3,
    pay_comments='A comment',
    underpayment_reason='331',
    note2contractor='Note to contractor')
$submissions = new \Upwork\API\Routers\Hr\Submissions($client);
$submissionId = 1234;
$params = array(
  "amount" => "10",
  "bonus" => "3",
  "pay_comments" => "A comment",
  "underpayment_reason" => "331",
  "note2contractor" => "Note to freelancer"
);
$submissions->approve($submissionId, $params);
submissions = Upwork::Api::Routers::Hr::Submissions.new(client)
submission_id = 1234
params = {
  'amount' => '10',
  'bonus' => '3',
  'pay_comments' => 'A comment',
  'underpayment_reason' => '331',
  'note2contractor' => 'Note to freelancer'
}
submissions.approve(submission_id, params)
import com.Upwork.api.Routers.Hr.Submissions;
import java.util.HashMap;

Submissions submissions = new Submissions(client);
String submissionId = "1234";
HashMap<String, String> params = new HashMap<String, String>();
params.put("amount", "10");
params.put("bonus", "3");
params.put("pay_comments", "A comment");
params.put("underpayment_reason", "331");
params.put("note2contractor", "Note to freelancer");

submissions.approve(submissionId, params);
var Submissions = require('upwork-api/lib/routers/hr/submissions.js').Submissions;

var submissions = new Submissions(api);
var submissionId = 1234;
var params = {
  'amount' => '10',
  'bonus' => '3',
  'pay_comments' => 'A comment',
  'underpayment_reason' => '331',
  'note2contractor' => 'Note to freelancer'
};
submissions.approve(submissionId, params, data) {
  console.log(data);
});
$submissions = Upwork::Api::Routers::Hr::Submissions->new($api);
$submission_id = 1234;
my %params = {
  'amount' => '10',
  'bonus' => '3',
  'pay_comments' => 'A comment',
  'underpayment_reason' => '331',
  'note2contractor' => 'Note to freelancer'
};
$submissions->approve($submission_id, %params);
import ( submissionsUpwork "github.com/upwork/golang-upwork/api/routers/hr/submissions" )

submissions := submissionsUpwork.New(client)
submissionId = "1234";
params := make(map[string]string)
params["amount"] = "10"
params["bonus"] = "3"
params["pay_comments"] = "A comment"
params["underpayment_reason"] = "331"
params["note2contractor"] = "Note to freelancer"

submissions.Approve(submissionId, params)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'message': 'ok',
  'server_time': 1405516669
}

Reject a milestone submission

Returns

Returns 200 OK in case of success.

DEFINITION
client.hr_v3.reject_submission(
    submission_id, note2contractor)
$submissions->reject(
  integer $submissionId, array $params );
submissions.reject(submission_id, params)
submissions.reject(
  String submissionId,
  HashMap<String, String> params);
submissions.reject(submissionId, params, callback);
$submissions->reject($submission_id, %params);
submissions.Reject(submissionId, HashMap<String, String> params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr_v3.reject_submission(
   submission_id, 'Fix title in Firefox')
$submissions = new \Upwork\API\Routers\Hr\Submissions($client);
$submissionId = 1234;
$params = array(
  "note2contractor" => "Note to freelancer"
);
$submissions->reject($submissionId, $params);
submissions = Upwork::Api::Routers::Hr::Submissions.new(client)
submission_id = 1234
params = {
  'note2contractor' => 'Note to freelancer'
}
submissions.reject(submission_id, params)
import com.Upwork.api.Routers.Hr.Submissions;
import java.util.HashMap;

Submissions submissions = new Submissions(client);
String submissionId = "1234";
HashMap<String, String> params = new HashMap<String, String>();
params.put("note2contractor", "Note to freelancer");

submissions.reject(submissionId, params);
var Submissions = require('upwork-api/lib/routers/hr/submissions.js').Submissions;

var submissions = new Submissions(api);
var submissionId = 1234;
var params = {
  'note2contractor': 'Note to freelancer'
};
submissions.reject(submissionId, params, function(error, data) {
  console.log(data);
});
my $submissions = Upwork::Api::Routers::Hr::Submissions->new($api);
my $submission_id = 1234;
my %params = {
  'note2contractor' => 'Note to freelancer'
};
$submissions->reject($submission_id, %params);
import ( submissionsUpwork "github.com/upwork/golang-upwork/api/routers/hr/submissions" )

submissions := submissionsUpwork.New(client)
submissionId = "1234";
params := make(map[string]string)
params["note2contractor"] = "Note to freelancer"

submissions.Reject(submissionId, params)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'message': 'ok',
  'server_time': 1405516669
}

Payments

This section describes resources that allow you to make custom payments (bonuses) and list payments made.

Make custom payment

Returns

This resource returns the adjustment reference.

DEFINITION
client.hr.post_team_adjustment(
    team_reference, engagement_reference, comments,
    amount=None, charge_amount=None, notes=None)
$payments->submitBonus( integer $teamReference,
                        array $params );
payment.submit_bonus(team_reference, params)
payments.submitBonus(
  String teamReference,
  java.util.HashMap<String,String> params);
payments.submitBonus(
  teamReference, params, callback);
$payment->submit_bonus($team_reference, $params);
payments.SubmitBonus(teamReference, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.hr.post_team_adjustment(
    12345, 78910, 'Test bonus payment', amount=20,
    notes='Good job')
$payments = new \Upwork\API\Routers\Payments($client);
$params = array(
  "engagement__reference" => 78910,
  "comment" => "Test bonus payment",
  "amount" => 20
);
$payments->submitBonus(12345, $params);
payments = Upwork::Api::Routers::Payments.new(client)
params = {
  'engagement__reference' => 78910,
  'comment' => 'Test bonus payment',
  'amount' => 20
}
payments.submit_bonus(12345, params)
import com.Upwork.api.Routers.Payments;
import java.util.HashMap;

Payments payments = new Payments(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("engagement__reference", "78910");
params.put("comment", "Test bonus payment");
params.put("amount", "20");

payments.submitBonus("12345", params);
var Payments = require('upwork-api/lib/routers/payments.js').Payments;

var payments = new Payments(api);
teamReference = '12345';
params = {
  'engagement__reference': 78910,
  'comment': 'Test bonus payment',
  'amount': 20
}
payments.submitBonus(teamReference, params, function(error, data) {
  console.log(data);
});
my $payments = Upwork::Api::Routers::Payments->new($api);
my %params = {
  'engagement__reference' => 78910,
  'comment' => 'Test bonus payment',
  'amount' => 20
};
$payments->submit_bonus(12345, %params);
import ( paymentsUpwork "github.com/upwork/golang-upwork/api/routers/payments" )

payments := paymentsUpwork.New(client)
params := make(map[string]string)
params["engagement__reference"] = "78910"
params["comment"] = "Test bonus payment"
params["amount"] = "20"
payments.SubmitBonus("12345", params)
EXAMPLE RESPONSE
{'reference': '011223344'}

MC to Messages Transition

This section describes API transition from MC to Messages.

_images/mc-to-messages.png

Below you can find the details and requirements for each API.

Messages

This section describes resources that allow you to get/update rooms and send messages.

Retrieve rooms information

Returns

Returns the information on the rooms. Details on returned data:

DEFINITION
EXAMPLE RESPONSE
{
  'auth_user': {
  # ..
  },
  'server_time': 123456790,
  'rooms': [
    {
      'roomId': 'room_12345',
      # ..
    }
    # ..
  ]
}

Get a specific room information

Returns

Returns the data on the room queried. Details on returned data:

DEFINITION
EXAMPLE RESPONSE
{
  'auth_user': {
  # ..
  },
  'server_time': 123456790,
  'room': {
    'roomId': 'room_12345',
    'roomName': 'Room name',
    # ..
  }
}

Get a specific room by offer ID

Returns

Returns the information on the offer ID queried. Details on returned data:

DEFINITION
EXAMPLE RESPONSE
{
  'auth_user': {
  # ..
  },
  'server_time': 123456790,
  'room': {
    'roomId': 'room_12345',
    'roomName': 'Room name',
    # ..
  }
}

Get a specific room by application ID

Returns

Returns the information on the application ID queried. Details on returned data:

DEFINITION
EXAMPLE RESPONSE
{
  'auth_user': {
  # ..
  },
  'server_time': 123456790,
  'room': {
    'roomId': 'room_12345',
    'roomName': 'Room name',
    # ..
  }
}

Get a specific room by contract ID

Returns

Returns the information on the contract ID queried. Details on returned data:

DEFINITION
EXAMPLE RESPONSE
{
  'auth_user': {
  # ..
  },
  'server_time': 123456790,
  'room': {
    'roomId': 'room_12345',
    'roomName': 'Room name',
    # ..
  }
}

Create a new room

Warning

All parameters must be wrapped into json object, e.g. {“roomName”:”Group Project”,”roomType”:”GROUP”, ... }, and sent as a separate parameter called room.

Returns

Returns HTTP code 201. Includes a link to the room in the Location header and the room ID in the response body, if creation was successful.

DEFINITION

Send a message to a room

Warning

All parameters must be wrapped into json object, e.g. {“message”: “a message”, ...}, and sent as a separate parameter called story.

Returns

Returns HTTP code 201.

DEFINITION

Update a room settings

Warning

All parameters must be wrapped into json object, e.g. {“isFavorite”: “true”}, and sent as a separate parameter called update_request.

Returns

Returns HTTP code 200.

DEFINITION

Archive or rename a room

Warning

All parameters must be wrapped into json object, e.g. {“isReadOnly”: “true”}, and sent as a separate parameter called metadata.

Returns

Returns HTTP code 200.

DEFINITION

Activities

This section describes a set of resources that allow you to manage activities – Upwork task management system. The term “activity” is used with the meaning of “task” throughout the following reference documentation.

Activities API resources allow you to assign specific activities to freelancers. These resources require authentication and require the user to be a member of the referenced company or team, and have hiring permissions.

If a company has no teams, use the company_id as the team_id.

You can find company_id via Companies & Teams API, List teams in company. The value you need is returned in the parent_team__id field.

List team activities

Returns

Details on the returned data:

record_id
The record ID of the activities. Each activity has a unique ID (users have no control over this number and it should only be used as a reference).
company_id
This is the ID of the company.
user_id
The Upwork ID of the user.
code
This is specified by the user. It could be used to reference a bug ID on a third-party system.
description
The text description contained within the activity.
URL
This is specified by the user. It can be used to link to a third-party bug tracking system or any related URL.
DEFINITION
client.task.get_team_tasks(company_id, team_id)
$activities->getList( string $company, string $team );
activities.get_list(company, team)
activities.getList(
  String company, String team);
activities.getList(company, team, callback);
$activities->get_list($company, $team);
activities.GetList(company, team)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.task.get_team_tasks('123abc', '567def')
$activities = new \Upwork\API\Routers\Activities\Team($client);
$activities->getList("123abc", "567def");
activities = Upwork::Api::Routers::Activities::Team.new(client)
activities.get_list('123abc', '567def')
import com.Upwork.api.Routers.Activities.Team;

Team activities = new Team(client);
activities.getList("123abc", "567def");
var Team = require('upwork-api/lib/routers/activities/team.js').Team;

var activities = new Team(api);
activities.getList('123abc', '567def', function(error, data) {
  console.log(data);
});
my $activities = Upwork::Api::Routers::Activities::Team->new($api);
$activities->get_list('123abc', '567def');
import ( teamUpwork "github.com/upwork/golang-upwork/api/routers/activities/team" )

activities := teamUpwork.New(client)
activities.GetList("123abc", "567def")
EXAMPLE RESPONSE
[
  {
    'code': 'User task 01',
    'company_id': '567def',
    'created_time': '2014-07-17 10:54:30',
    'description': 'Descr',
    'engagements': {
      'engagement': '171318'
    },
    'level': 'team',
    'payment_verification_status': 'VERIFIED',
    'record_id': '65464',
    'status': 'active',
    'team_id': '123abc',
    'total_engagements': '1',
    'url': '',
    'user_id': ''
  },
  {
    # Another activity
  },
  # ...
]

List activities for specific engagement

Returns

Returns the list of activities that are currently assigned to the specified engagement.

DEFINITION
client.task_v2.list_engagement_activities(engagement_ref)
$activities->getSpecific( integer $engagementRef );
activities.get_specific(engagemnet_ref)
activities.getSpecific(String engagementRef);
activities.getSpecific(engagementRef, callback);
$activities->get_specific($engagemnet_ref);
activities.GetSpecific(engagementRef)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.task_v2.list_engagement_activities('1234')
$activities = new \Upwork\API\Routers\Activities\Engagement($client);
$activities->getSpecific(1234);
activities = Upwork::Api::Routers::Activities::Engagement.new(client)
activities.get_specific(1234)
import com.Upwork.api.Routers.Activities.Engagement;

Engagement activities = new Engagement(client);
activities.getSpecific("1234");
activities.getSpecific(engagementRef, callback);
$activities->get_specific($engagemnet_ref);
activities.GetSpecific(engagementRef)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.task_v2.list_engagement_activities('1234')
$activities = new \Upwork\API\Routers\Activities\Engagement($client);
$activities->getSpecific(1234);
activities = Upwork::Api::Routers::Activities::Engagement.new(client)
activities.get_specific(1234)
import com.Upwork.api.Routers.Activities.Engagement;

Engagement activities = new Engagement(client);
activities.getSpecific("1234");
var Engagement = require('upwork-api/lib/routers/activities/engagement.js').Engagement;

var activities = new Engagement(api);
activities.getSpecific('1234', function(error, data) {
  console.log(data);
});
my $activities = Upwork::Api::Routers::Activities::Engagement->new($api);
$activities->get_specific(1234);
import ( engagementUpwork "github.com/upwork/golang-upwork/api/routers/activities/engagement" )

activities := engagementUpwork.New(client)
activities.GetSpecific("1234")
EXAMPLE RESPONSE
{
  'server_time': '1406027484',
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'task_sets': {
    'task_set': {
      'required': '1',
      'type': 'otask',
      'tasks': {
        'task': [
          {
            'description': 'Test task 01',
            'url': '',
            'code': 'test01',
            'id': '{type=otask,cny=mytestcompany:mysecondsubteam,code=test01,team=mytestcompany:mysecondsubteam,level=team}'
          },
          {
            # Another activity
          },
          # ...
        ]
      },
      'hash': '59c31ed3d95d378740fa65218d8de7ae'
    }
  }
}

Get team activity by code

Returns

In case of multiple activities requested, a list will be returned.

Details on the returned data:

record_id
The record ID of the activities. Each activity has a unique ID (users have no control over this number and it should only be used as a reference).
company_id
This is the ID of the company.
user_id
The Upwork ID of the user.
code
This is specified by the user. It could be used to reference a bug ID on a third-party system.
description
The text description contained within the activity.
URL
This is specified by the user. It can be used to link to a third-party bug tracking system or any related URL.
DEFINITION
client.task.get_team_specific_tasks(
    company_id, team_id, task_codes)
$activities->getSpecificList( string $company,
                              string $team, string $code );
activities.get_specific_list(company, team, code)
activities.getSpecificList(
  String company, String team, String code);
activities.getSpecificList(
  company, team, code, callback);
$activities->get_specific_list($company, $team, $code);
activities.GetSpecificList(company, team, code)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.task.get_team_specific_tasks(
    '123abc', '678def', ['User task 01'])
$activities = new \Upwork\API\Routers\Activities\Team($client);
$activities->getSpecificList("123abc", "678def",
                             "User task 01");
activities = Upwork::Api::Routers::Activities::Team.new(client)
activities.get_specific_list('123abc', '678def',
                             'User task 01')
import com.Upwork.api.Routers.Activities.Team;

Team activities = new Team(client);
activities.getSpecificList("123abc", "678def", "User task 01");
var Team = require('upwork-api/lib/routers/activities/team.js').Team;

var activities = new Team(api);
activities.getSpecificList('123abc', '567def', 'User task 01', function(error, data) {
  console.log(data);
});
my $activities = Upwork::Api::Routers::Activities::Team->new($api);
$activities->get_specific_list('123abc', '678def', 'User task 01');
import ( teamUpwork "github.com/upwork/golang-upwork/api/routers/activities/team" )

activities := teamUpwork.New(client)
activities.GetSpecificList("123abc", "678def", "User task 01")
EXAMPLE RESPONSE

In case of multiple activities requested, a list will be returned.

{
  'code': 'User task 01',
  'company_id': '123abc',
  'created_time': '2014-07-17 10:54:30',
  'description': 'Descr',
  'engagements': {
    'engagement': '171318'
  },
  'level': 'team',
  'payment_verification_status': 'VERIFIED',
  'record_id': '65464',
  'status': 'active',
  'team_id': '678def',
  'url': '',
  'user_id': ''
}

Create activity at team level

Returns

If the call is successful, the server returns a 200 OK message. If the call fails a 403 error message is returned.

DEFINITION
client.task.post_team_task(
    company_id, team_id, code, description, url,
    engagements=None, all_in_company=None)
$activities->addActivity( string $company,
                          string $team, string $params );
activities.add_activity(company, team, params)
activities.addActivity(
  String company,
  String team,
  java.util.HashMap<String,String> params);
activities.addActivity(
  company, team, params, callback);
$activities->add_activity($company, $team, %params);
activities.AddActivity(company, team, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.task.post_team_task(
    '123abc', '678def', 'Team task 01', 'Desc', '',
    all_in_company=1)
$activities = new \Upwork\API\Routers\Activities\Team($client);
$params = array(
  "code" => "Team task 01",
  "description" => "Desc",
  "all_in_company" => "1"
);
$activities->addActivity("123abc", "678def", $params);
activities = Upwork::Api::Routers::Activities::Team.new(client)
params = {
  'code' => 'Team task 01',
  'description' => 'Desc',
  'all_in_company' => '1'
}
activities.add_activity('123abc', '678def', params)
import com.Upwork.api.Routers.Activities.Team;
import java.util.HashMap;

Team activities = new Team(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("code", "Team task 01");
params.put("description", "Desc");
params.put("all_in_company", "1");

activities.addActivity("123abc", "678def", params);
var Team = require('upwork-api/lib/routers/activities/team.js').Team;

var activities = new Team(api);
var params = {
  'code': 'Team task 01',
  'description': 'Desc',
  'all_in_company': '1'
};
activities.addActivity('123abc', '678def', params, function(error, data) {
  console.log(data);
});
my $activities = Upwork::Api::Routers::Activities::Team->new($api);
my %params = {
  'code' => 'Team task 01',
  'description' => 'Desc',
  'all_in_company' => '1'
};
$activities->add_activity('123abc', '678def', %params);
import ( teamUpwork "github.com/upwork/golang-upwork/api/routers/activities/team" )


activities := teamUpwork.New(client)
params := make(map[string]string)
params["code"] = "Team task 01"
params["description"] = "Desc"
params["all_in_company"] = "1"

activities.AddActivity("123abc", "678def", params)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'server_time': '1405695093',
  'tasks': {
    'code': 'Team task 01',
    'company__reference': '377329',
    'company_id': '123abc',
    'created_time': '',
    'description': 'Desc',
    'engagements': '',
    'record_id': '65491',
    'reference': '65491',
    'status': '',
    'team__reference': '377329',
    'team_id': '678def',
    'url': '',
    'user__reference': '',
    'user_id': ''
  }
}

Update activity at team level

If you want to update an activity for the whole company, just use the company_id as the team_id.

Returns

If the call is successful, the server returns a 200 OK message. If the call fails a 403 error message is returned.

DEFINITION
client.task.put_team_task(
    company_id, team_id, code, description, url,
    engagements=None, all_in_company=None)
$activities->updateActivity( string $company, string $team,
                             string $code, string $params );
activities.update_activities(company, team, code, params)
activities.updateActivity(
  String company,
  String team,
  String code,
  java.util.HashMap<String,String> params);
activities.updateActivity(
  company, team, code, params, callback);
$activities->update_activities($company, $team, $code, %params);
activities.UpdateActivity(company, team, code, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.task.put_team_task(
    '123abc', '456def', 'Team task 01',
    'Desc updated', '', all_in_company=1)
$activities = new \Upwork\API\Routers\Activities\Team($client);
$params = array(
  "description" => "Desc updated",
  "all_in_company" => "1"
);
$activities->updateActivity("123abc", "678def",
                            "Team task 01", $params);
activities = Upwork::Api::Routers::Activities::Team.new(client)
params = {
  'description' => 'Desc updated',
  'all_in_company' => '1'
}
activities.update_activities('123abc', '678def',
                            'Team task 01', params)
import com.Upwork.api.Routers.Activities.Team;
import java.util.HashMap;

Team activities = new Team(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("description", "Desc updated");
params.put("all_in_company", "1");

activities.updateActivity(
  "123abc", "678def", "Team task 01", params);
var Team = require('upwork-api/lib/routers/activities/team.js').Team;

var activities = new Team(api);
var params = {
  'description': 'Desc updated',
  'all_in_company': '1'
};
activities.updateActivity('123abc', '678def', 'Team task 01', params, function(error, data) {
  console.log(data);
});
my $activities = Upwork::Api::Routers::Activities::Team->new($api);
my %params = {
  'description' => 'Desc updated',
  'all_in_company' => '1'
};
$activities->update_activities('123abc', '678def', 'Team task 01', %params);
import ( teamUpwork "github.com/upwork/golang-upwork/api/routers/activities/team" )


activities := teamUpwork.New(client)
params := make(map[string]string)
params["description"] = "Desc updated"
params["all_in_company"] = "1"

activities.UpdateActivity("123abc", "678def", "Team task 01", params)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'server_time': '1405746487',
  'tasks': {
    'message': 'updated'
  }
}

Assign engagements to the list of activities

Returns

Returns 200 OK in case of success.

DEFINITION
client.task.assign_engagement(
    company_id, team_id, engagement, task_codes=None)
$activities->assign( string $company, integer $team,
                     mixed $engagement, mixed $params );
activities.assign(company, team, engagement, params)
activities.assign(
  String company,
  String team,
  String engagement,
  java.util.HashMap<String,String> params);
activities.assign(
  company, team, engagementRef,
  params, callback);
$activities->assign($company, $team, $engagement, %params);
activities.Assign(company, team, engagement, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.task.assign_engagement('123abc', '678def, '12345', ['Team task 01'])
$activities = new \Upwork\API\Routers\Activities\Engagement($client);
$params = array(
  "tasks" => "Team task 01"
);
$activities->assign("123abc", "678def", 12345, $params);
activities = Upwork::Api::Routers::Activities::Engagement.new(client)
params = {
  'tasks' => 'Team task 01'
}
activities.assign('123abc', '678def', 12345, params)
import com.Upwork.api.Routers.Activities.Engagement;
import java.util.HashMap;

Engagement activities = new Engagement(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("tasks", "Team task 01");

activities.assign(
  "123abc", "678def", "12345", params);
var Engagement = require('upwork-api/lib/routers/activities/engagement.js').Engagement;

var activities = new Engagement(api);
var params = {'tasks': 'Team task 01'};
activities.assign('123abc', '678def', '12345', params, function(error, data) {
  console.log(data);
});
my $activities = Upwork::Api::Routers::Activities::Engagement->new($api);
my %params = {
  'tasks' => 'Team task 01'
};
$activities->assign('123abc', '678def', 12345, %params);
import ( engagementUpwork "github.com/upwork/golang-upwork/api/routers/activities/engagement" )


activities := engagementUpwork.New(client)
params := make(map[string]string)
params["tasks"] = "Team task 01"

activities.Assign("123abc", "678def", "12345", params)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'server_time': '1405882462',
  'tasks': ''
}

Assign to specific engagement the list of activities

Returns

Returns 200 OK in case of success.

DEFINITION
client.task_v2.assign_to_engagement(engagement_ref, task_codes=None)
$activities->assignToEngagement( integer $engagementRef, mixed $params );
activities.assign_to_engagement(engagemnet_ref, params)
activities.assignToEngagement(
  String engagementRef,
  java.util.HashMap<String,String> params);
activities.assignToEngagement(engagementRef, params, callback);
$activities->assign_to_engagement($engagemnet_ref, %params);
activities.AssignToEngagement(engagementRef, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.task_v2.assign_to_engagement('1234', ['Team task 01'])
$activities = new \Upwork\API\Routers\Activities\Engagement($client);
$params = array(
  "tasks" => "Team task 01"
);
$activities->assignToEngagement(1234, $params);
activities = Upwork::Api::Routers::Activities::Engagement.new(client)
params = {
  'tasks' => 'Team task 01'
}
activities.assign_to_engagement(1234, params)
import com.Upwork.api.Routers.Activities.Engagement;
Engagement activities = new Engagement(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("tasks", "Team task 01");
activities.assignToEngagement("1234", params);
var Engagement = require('upwork-api/lib/routers/activities/engagement.js').Engagement;

var activities = new Engagement(api);
var params = {'tasks': 'Team task 01'};
activities.assignToEngagement('1234', params, function(error, data) {
  console.log(data);
});
my $activities = Upwork::Api::Routers::Activities::Engagement->new($api);
my %params = {
  'tasks' => 'Team task 01'
};
$activities->assign_to_engagement(1234, %params);
import ( engagementUpwork "github.com/upwork/golang-upwork/api/routers/activities/engagement" )

activities := engagementUpwork.New(client)
params := make(map[string]string)
params["tasks"] = "Team task 01"
activities.AssignToEngagement("1234", params)
EXAMPLE RESPONSE
{
  'server_time': '1406027484',
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'message': 'assigned'
}

Archive activities

Returns

Returns 200 OK in case of success.

DEFINITION
client.archive_team_task(company_id, team_id, task_code)
$activities->archiveActivities( string $company,
                                string $team, string $code );
activities.archive_activities(company, team, code)
activities.archiveActivity(
  String company, String team, String code);
activities.archiveActivity(
  company, team, code, callback);
$activities->archive_activities($company, $team, $code);
activities.ArchiveActivity(company, team, code)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.task.archive_team_task('123abc', '678def', 'Team task 01')
$activities = new \Upwork\API\Routers\Activities\Team($client);
$activities->archiveActivities("123abc", "678def",
                               "Team task 01");
activities = Upwork::Api::Routers::Activities::Team.new(client)
activities.archive_activities('123abc', '678def',
                               'Team task 01')
import com.Upwork.api.Routers.Activities.Team;

Team activities = new Team(client);
activities.archiveActivity(
  "123abc", "678def", "Team task 01");
var Team = require('upwork-api/lib/routers/activities/team.js').Team;

var activities = new Team(api);
activities.archiveActivity('123abc', '678def', 'Team task 01', function(error, data) {
  console.log(data);
});
my $activities = Upwork::Api::Routers::Activities::Team->new($api);
$activities->archive_activities('123abc', '678def','Team task 01');
import ( teamUpwork "github.com/upwork/golang-upwork/api/routers/activities/team" )

activities := teamUpwork.New(client)
activities.ArchiveActivity("123abc", "678def", "Team task 01")
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'server_time': '1405883808',
  'tasks': '1'
}

Unarchive activities

Returns

Returns 200 OK in case of success.

DEFINITION
client.task.unarchive_team_task(company_id, team_id, task_code)
$activities->unarchiveActivities( string $company,
                                  string $team,
                                  string $code );
activities.unarchive_activities(company, team, code)
activities.unarchiveActivity(
  String company, String team, String code);
activities.unarchiveActivity(
  company, team, code, callback);
$activities->unarchive_activities($company, $team, $code);
activities.UnarchiveActivity(company, team, code)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.task.unarchive_team_task('123abc', '678def', 'Team task 01')
$activities = new \Upwork\API\Routers\Activities\Team($client);
$activities->unarchiveActivities("123abc", "678def",
                                 "Team task 01");
activities = Upwork::Api::Routers::Activities::Team.new(client)
activities.unarchive_activities('123abc', '678def',
                                 'Team task 01')
import com.Upwork.api.Routers.Activities.Team;

Team activities = new Team(client);
activities.unarchiveActivity(
"123abc", "678def", "Team task 01");
var Team = require('upwork-api/lib/routers/activities/team.js').Team;

var activities = new Team(api);
activities.unarchiveActivity('123abc', '678def', 'Team task 01', function(error, data) {
  console.log(data);
});
my $activities = Upwork::Api::Routers::Activities::Team->new($api);
$activities->unarchive_activities('123abc', '678def','Team task 01');
import ( teamUpwork "github.com/upwork/golang-upwork/api/routers/activities/team" )

activities := teamUpwork.New(client)
activities.UnarchiveActivity("123abc", "678def", "Team task 01")
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'server_time': '1405884666',
  'tasks': '1'
}

Update bulk of activities

Note

Currently this API call gives no control over engagements assignment or archiving/unarchiving of activities. Use it at your own risk.

Returns

If the call is successful, the server returns a 200 OK message. If the call fails a 403 error message is returned.

DEFINITION
client.task.update_batch_tasks(company_id, csv_data)
$activities->updateBatch( string $company, string $params );
activities.update_batch(company, params)
activities.updateBatch(
  String company,
  java.util.HashMap<String,String> params);
activities.updateBatch(company, params, callback);
$activities->update_batch($company, %params);
activities.UpdateBatch(company, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
bulk_data = '"{company_id}","{team_id}","{user_id}","User task 01","Desc bulk",""<br>"{company_id}","{team_id}","{user_id}","User task 02","Desc bulk",""'
client.task.update_batch_tasks(
    "123abc", bulk_data.format(company_id='123abc',
                               team_id='678def',
                               user_id='john_freelancer')
$activities = new \Upwork\API\Routers\Activities\Company($client);
$companyId = '123abc';
$teamId = '678def';
$userId = 'john_freelancer';
$params = array(
  "data" => "\"$companyId\",\"$teamId\",\"$userId\",\"User task 01\",\"Desc bulk\",\"\"<br>\"$companyId\",\"$teamId\",\"$userId\",\"User task 02\",\"Desc bulk\",\"\""
);
$activities->updateBatch("123abc", $params);
activities = Upwork::Api::Routers::Activities::Team.new(client)
company_id = '123abc'
team_id = '678def'
user_id = 'john_freelancer'
params = {
  'data' => '"#{company_id}","#{team_id}","#{user_id}","User task 01","Desc bulk",""<br>"#{company_id}","#{team_id}","#{user_id}","User task 02","Desc bulk",""'
}
activities.update_batch('123abc', params)
import com.Upwork.api.Routers.Activities.Team;
import java.util.HashMap;

Team activities = new Team(client);
HashMap<String, String> params = new HashMap<String, String>();
String companyId = "123abc";
String teamId = "123abc";
String userId = "john_freelancer";
String data = String.format("\"%s\",\"%s\",\"%s\",\"User task 01\",\"Desc bulk\",\"\"<br>\"%s\",\"%s\",\"%s\",\"User task 02\",\"Desc bulk\",\"\"", companyId, teamId, userId, companyId, teamId, userId);
params.put("data", data);

activities.updateBatch("123abc", params);
var Team = require('upwork-api/lib/routers/activities/team.js').Team;

var activities = new Team(api);
var companyId = '123abc';
var teamId = '678def';
var userId = 'john_freelancer';
var params = {
  'data': '"' + companyId + '","' + teamId + '","' + userId + '","User task 01","Desc bulk",""<br>"' + companyId + '","' + teamId + '","' + userId + '","User task 02","Desc bulk",""'
};
activities.updateBatch(companyId, params, function(error, data) {
  console.log(data);
});
my $activities = Upwork::Api::Routers::Activities::Team->new($api);
my $company_id = '123abc';
my $team_id = '678def';
my $user_id = 'john_freelancer';
my %params = {
  'data' => '"#{company_id}","#{team_id}","#{user_id}","User task 01","Desc bulk",""<br>"#{company_id}","#{team_id}","#{user_id}","User task 02","Desc bulk",""'
};
$activities->update_batch('123abc', %params);
import ( teamUpwork "github.com/upwork/golang-upwork/api/routers/activities/team" )


activities := teamUpwork.New(client)
params := make(map[string]string)
companyId = "123abc";
teamId = "123abc";
userId = "john_freelancer";
data = String.Format("\"%s\",\"%s\",\"%s\",\"User task 01\",\"Desc bulk\",\"\"<br>\"%s\",\"%s\",\"%s\",\"User task 02\",\"Desc bulk\",\"\"", companyId, teamId, userId, companyId, teamId, userId)
params.Put("data", data)

activities.UpdateBatch("123abc", params)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'server_time': '1405697909',
  'tasks': '2'
}

Snapshots

This section describes resources that allow you to get activity snapshots from a user account, in a company’s team, at specific points in time. You can also update and delete snapshots. These resources can only be used with the teams the user has access to. An error will be returned if the currently authorized user does not have access to the teammate details being requested.

Get snapshot

Returns

Details on the response:

snapshot
Snapshot detail container.
status
Status of the snapshot. Can be: LOGIN, NORMAL, PRIVATE, EXIT
time
The GMT Unix timestamp when the snapshot was taken
billing_status
The billing status of the snapshot: non-billed.disconnected, billed.disconnected, billed.connected
activity
User activity. Aggregated number of keystrokes and mouse clicks.
online_presence
Indicates whether the user is online.
user
General details about the current user.
mouse_events_count
The number of mouse events associated with this snapshot.
company_id
Company ID associated with this snapshot.
timezone
User’s time zone
uid
The user ID.
keyboard_events_count
Number of keyboard events counted for this snapshot.
last_worked
The Unix timestamp indicating when the user last worked.
memo
Memo associated with the current time stamp.
active_window_title
The title of the active window when the snapshot was taken.
report24_img
URL to a graph that describes a user’s activity over a 24hr period.
computer_name
The name of the computer where the snapshot was taken.
online_presence_img
URL for the default online user activity
user_id
User ID associated with the current snapshot
client_version
The Upwork Time Tracker version used to take the snapshot
DEFINITION
client.team.get_snapshot(
    company_id, user_id, datetime=None)
$snapshots->get( string $company, string $username,
                 string $ts );
snapshots.get(company, username, ts)
snapshots.get(
  String company,
  String username,
  String ts);
snapshots.get(
  company, username, ts, callback);
$snapshots->get($company, $username, $ts);
snapshots.Get(company, username, ts)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.team.get_snapshot(
    '123abc', 'john_freelancer',
    datetime='20140101T090000Z,20140101T120000Z')
$snapshots = new \Upwork\API\Routers\Snapshot($client);
$snapshots->get("123abc", "john_freelancer",
               "20140101T090000Z,20140101T120000Z");
snapshots = Upwork::Api::Routers::Snapshot.new(client)
snapshots.get('123abc', 'john_freelancer',
               '20140101T090000Z,20140101T120000Z')
import com.Upwork.api.Routers.Snapshot;
Snapshot snapshots = new Snapshot(client);

snapshots.get(
  "123abc", "john_freelancer",
  "20140101T090000Z,20140101T120000Z");
var Snapshot = require('upwork-api/lib/routers/snapshot.js').Snapshot;

var snapshots = new Snapshot(api);
snapshots.get('123abc', 'john_freelancer', '20140101T090000Z,20140101T120000Z', function(error, data) {
  console.log(data);
});
my $snapshots = Upwork::Api::Routers::Snapshot->new($api);
$snapshots->get('123abc', 'john_freelancer', '20140101T090000Z,20140101T120000Z');
import ( snapshotUpwork "github.com/upwork/golang-upwork/api/routers/snapshot" )

snapshots := snapshotUpwork.New(client)
snapshots.Get("123abc", "john_freelancer", "20140101T090000Z,20140101T120000Z")
EXAMPLE RESPONSE
{
  'account_status': 'enabled',
  'active_window_title': '',
  'activity': '0',
  'billing_status': 'non-billed.disconnected',
  'cellts': '',
  'client_version': '',
  'company_id': 'unazcm8kj7ytdrwwgc-pkq',
  'computer_name': '',
  'digest': '',
  'keyboard_events_count': '0',
  'memo': '',
  'mouse_events_count': '0',
  'online_presence': '0,0,0,0...',
  'online_presence_img': 'https://...',
  'report24_img': 'https://...',
  'status': 'PRIVATE',
  'team_name': 'John Test oAuth API',
  'teamroom_api': '/api/team/v1/teamrooms/unazcm8kj7ytdrwwgc-pkq.json',
  'time': '1405919907',
  'timezone': 'Asia/Omsk',
  'uid': '',
  'user': {'archiving_time': '1405555200',
  'creation_time': '1405434052',
  'first_name': 'John',
  'last_name': 'Panshine',
  'mail': 'john_freelancer@example.com',
  'messenger_id': None,
  'messenger_type': None,
  'timezone': 'Asia/Omsk',
  'timezone_offset': '25200',
  'uid': 'john_freelancer'},
  'user_id': 'john_freelancer',
  'workdiary_api': '/api/team/v1/workdiaries/unazcm8kj7ytdrwwgc-pkq/john_freelancer/20140721.json'
}

Update snapshot memo

Returns

If the snapshot is updated, a 200 OK status is returned.

DEFINITION
client.team.update_snapshot(
    company_id, user_id, memo, datetime=None)
$snapshots->update( string $company, string $username,
                   string $ts, array $params );
snapshots.update(company, username, ts, params)
snapshots.update(
  String company,
  String username,
  String ts,
  java.util.HashMap<String,String> params);
snapshots.update(
  company, username, ts, params,
  callback);
$snapshots->update($company, $username, $ts, %params);
snapshots.Update(company, username, ts, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.team.update_snapshot(
    '123abc', 'john_freelancer', 'New memo',
    datetime='20140101T090000Z')
$snapshots = new \Upwork\API\Routers\Snapshot($client);
$params = array("memo" => "New memo");
$snapshots->update("123abc", "john_freelancer",
                  "20140101T090000Z,20140101T120000Z",
                  $params);
snapshots = Upwork::Api::Routers::Snapshot.new(client)
params = {'memo' => 'New memo'}
snapshots.update('123abc', 'john_freelancer',
                  '20140101T090000Z,20140101T120000Z',
                  params)
import com.Upwork.api.Routers.Snapshot;
import java.util.HashMap;

Snapshot snapshots = new Snapshot(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("memo", "New memo");

snapshots.update(
  "123abc", "john_freelancer",
  "20140101T090000Z,20140101T120000Z",
  params);
var Snapshot = require('upwork-api/lib/routers/snapshot.js').Snapshot;

var snapshots = new Snapshot(api);
params = {'memo': 'New memo'};
snapshots.update('123abc', 'john_freelancer', '20140101T090000Z,20140101T120000Z', params, function(error, data) {
  console.log(data);
});
my $snapshots = Upwork::Api::Routers::Snapshot->new($api);
my %params = {'memo' => 'New memo'};
$snapshots->update('123abc', 'john_freelancer', '20140101T090000Z,20140101T120000Z', %params);
import ( snapshotUpwork "github.com/upwork/golang-upwork/api/routers/snapshot" )

snapshots := snapshotUpwork.New(client)
params := make(map[string]string)
params["memo"] = "New memo"

snapshots.Update("123abc", "john_freelancer", "20140101T090000Z,20140101T120000Z", params)
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'server_time': 1405935643,
  'snapshot': 'added'
}

Delete snapshot

Returns

If the snapshot is deleted, a 200 OK message is returned.

DEFINITION
client.team.delete_snapshot(company_id, user_id, datetime=None)
$snapshots->delete( string $company, string $username,
                   string $ts );
snapshots.delete(company, username, ts)
snapshots.delete(
  String company,
  String username,
  String ts);
snapshots.delete(
  company, username, ts, callback);
$snapshots->delete($company, $username, $ts);
snapshots.Delete(company, username, ts)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.team.delete_snapshot(
    '123abc', 'john_freelancer',
    datetime='20140101T090000Z,20140101T120000Z')
$snapshots = new \Upwork\API\Routers\Snapshot($client);
$snapshots->delete("123abc", "john_freelancer",
                  "20140101T090000Z,20140101T120000Z");
snapshots = Upwork::Api::Routers::Snapshot.new(client)
snapshots.delete('123abc', 'john_freelancer',
                  '20140101T090000Z,20140101T120000Z')
import com.Upwork.api.Routers.Snapshot;

Snapshot snapshots = new Snapshot(client);
snapshots.delete(
  "123abc", "john_freelancer",
  "20140101T090000Z,20140101T120000Z");
var Snapshot = require('upwork-api/lib/routers/snapshot.js').Snapshot;

var snapshots = new Snapshot(api);
snapshots.delete('123abc', 'john_freelancer', '20140101T090000Z,20140101T120000Z', function(error, data) {
  console.log(data);
});
my $snapshots = Upwork::Api::Routers::Snapshot->new($api);
$snapshots->delete('123abc', 'john_freelancer', '20140101T090000Z,20140101T120000Z');
import ( snapshotUpwork "github.com/upwork/golang-upwork/api/routers/snapshot" )

snapshots := snapshotUpwork.New(client)
snapshots.Delete("123abc", "john_freelancer", "20140101T090000Z,20140101T120000Z")
EXAMPLE RESPONSE
{
  'auth_user': {
    'first_name': 'John',
    'last_name': 'Johnson',
    'timezone': 'Asia/Omsk',
    'timezone_offset': '25200'
  },
  'server_time': 1405935643,
  'snapshot': 'deleted'
}

Get snapshot by Contract

Returns

Details on the response:

snapshot
Snapshot detail container.
status
Status of the snapshot. Valid values are: LOGIN, NORMAL, PRIVATE, EXIT.
time
The GMT Unix timestamp when the snapshot was taken.
billing_status
The billing status of the snapshot: non-billed.disconnected, billed.disconnected, billed.connected.
activity
User activity. Aggregated number of keystrokes and mouse clicks.
online_presence
Indicates whether the user is online.
user
General details about the current user.
mouse_events_count
The number of mouse events associated with this snapshot.
company_id
Company ID associated with this snapshot.
timezone
User’s time zone.
uid
The user ID.
keyboard_events_count
Number of keyboard events counted for this snapshot.
last_worked
The Unix timestamp indicating when the user last worked.
memo
Memo associated with the current time stamp.
active_window_title
The title of the active window when the snapshot was taken.
report24_img
URL to a graph that describes a user’s activity over a 24hr period.
computer_name
The name of the computer where the snapshot was taken.
online_presence_img
URL for the default online user activity.
user_id
User ID associated with the current snapshot.
client_version
The Upwork Time Tracker version used to take the snapshot.
DEFINITION
client.team.get_snapshot_by_contract(contract_id, datetime=None)
$snapshots->getByContract( string $contract_id, string $ts );
snapshots.get_by_contract(contract_id, ts)
snapshots.getByContract(String contractId, String ts);
snapshots.getByContract(contract_id, ts, callback);
$snapshots->get_by_contract($contract_id, $ts);
snapshots.GetByContract(contractId, ts)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.team.get_snapshot_by_contract(
    '1234', datetime='20140101T090000Z,20140101T120000Z')
$snapshots = new \Upwork\API\Routers\Snapshot($client);
$snapshots->getByContract("1234", "20140101T090000Z,20140101T120000Z");
snapshots = Upwork::Api::Routers::Snapshot.new(client)
snapshots.get_by_contract('1234', '20140101T090000Z,20140101T120000Z')
import com.Upwork.api.Routers.Snapshot;

Snapshot snapshots = new Snapshot(client);
snapshots.getByContract("1234", "20140101T090000Z,20140101T120000Z");
var Snapshot = require('upwork-api/lib/routers/snapshot.js').Snapshot;

var snapshots = new Snapshot(api);
snapshots.get_by_contract('1234', '20140101T090000Z,20140101T120000Z', function(error, data) {
  console.log(data);
});
my $snapshots = Upwork::Api::Routers::Snapshot->new($api);
$snapshots->get_by_contract('1234', '20140101T090000Z,20140101T120000Z');
import ( snapshotUpwork "github.com/upwork/golang-upwork/api/routers/snapshot" )

snapshots := snapshotUpwork.New(client)
snapshots.GetByContract("1234", "20140101T090000Z,20140101T120000Z")
EXAMPLE RESPONSE
{
  'account_status': 'enabled',
  'active_window_title': '',
  'activity': '0',
  'billing_status': 'non-billed.disconnected',
  'cellts': '',
  'client_version': '',
  'company_id': 'unazcm8kj7ytdrwwgc-pkq',
  'computer_name': '',
  'digest': '',
  'keyboard_events_count': '0',
  'memo': '',
  'mouse_events_count': '0',
  'online_presence': '0,0,0,0...',
  'online_presence_img': 'https://...',
  'report24_img': 'https://...',
  'status': 'PRIVATE',
  'team_name': 'John Test oAuth API',
  'teamroom_api': '/api/team/v1/teamrooms/unazcm8kj7ytdrwwgc-pkq.json',
  'time': '1405919907',
  'timezone': 'Asia/Omsk',
  'uid': '',
  'user': {'archiving_time': '1405555200',
  'creation_time': '1405434052',
  'first_name': 'John',
  'last_name': 'Panshine',
  'mail': 'john_freelancer@example.com',
  'messenger_id': None,
  'messenger_type': None,
  'timezone': 'Asia/Omsk',
  'timezone_offset': '25200',
  'uid': 'john_freelancer'},
  'user_id': 'john_freelancer',
  'workdiary_api': '/api/team/v1/workdiaries/unazcm8kj7ytdrwwgc-pkq/john_freelancer/20140721.json'
}

Update snapshot memo by Contract

Returns

If the snapshot is updated, a 200 OK status is returned.

DEFINITION
client.team.update_snapshot_by_contract(
    contract_id, memo, datetime=None)
$snapshots->updateByContract( string $contract_id,
                   string $ts, array $params );
snapshots.update_by_contract(company, username, ts, params)
snapshots.updateByContract(
  String contractId,
  String ts,
  java.util.HashMap<String,String> params);
snapshots.update_by_contract(
  contract_id, ts, params,
  callback);
$snapshots->update_by_contract($company, $username, $ts, %params);
snapshots.UpdateByContract(contractId, ts, params)
EXAMPLE REQUEST
import upwork
client = upwork.Client(public_key, secret_key, **credentials)
client.team.update_snapshot_by_contract(
    '1234', 'New memo', datetime='20140101T090000Z')
$snapshots = new \Upwork\API\Routers\Snapshot($client);
$params = array("memo" => "New memo");
$snapshots->updateByContract("123abc", "john_freelancer",
                  "20140101T090000Z,20140101T120000Z",
                  $params);
snapshots = Upwork::Api::Routers::Snapshot.new(client)
params = {'memo' => 'New memo'}
snapshots.update_by_contract('1234',
                  '20140101T090000Z,20140101T120000Z',
                  params)
import com.Upwork.api.Routers.Snapshot;
import java.util.HashMap;

Snapshot snapshots = new Snapshot(client);
HashMap<String, String> params = new HashMap<String, String>();
params.put("memo", "New memo");

snapshots.updateByContract(
  "1234",
  "20140101T090000Z,20140101T120000Z",
  params);
var Snapshot = require('upwork-api/lib/routers/snapshot.js').Snapshot;

var snapshots = new Snapshot(api);
params = {'memo':