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.

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

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

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

Keys Management

When an API key is created, it is associated with the current context selected in the top-right menu (e.g., personal or organizational context). Please note, API keys cannot be transferred between contexts after creation.

For organizational use, ensure that the correct organization is selected before generating the key. If a key is created under a personal context, it will remain associated with that individual account.

To simplify key management, organization administrators can delegate key creation and management to specific members by assigning the appropriate permissions. API keys created by authorized members within an organizational context are owned by the organization—not by the individual who generated them. Ownership remains with the organization even if the member later leaves.

Application Permissions

When you register a new application, you are asked to define a list of permissions to access third-party resource data; we call them “Application Permissions”. You can later modify the application 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.

Take into account that caching shouldn't go against Upwork ToS. Specifically, we don't allow storing data for more than 24 hours.

See the list of your registered applications (keys)

Permissions Troubleshooting

When executing API queries, Upwork checks for permissions granted to the API Key in context. If the API Key does not have the required permissions to execute the query, the following message is returned:

The client or authentication token doesn't have enough oauth2 permissions/scopes to access <list of fields>

Contact the Upwork support team if you need help extending or customizing your API Key Scopes.

Please note that the scope "Common Entities - Read-Only Access" will be required for all the cases.

Authentication (OAuth2)

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

You need to authenticate for all requests following the OAuth 2.0, RFC 6749.

                  query {
                    companySelector {
                      items {
                        title
                        organizationId
                      }
                    }
                  }
                  

                  curl --request POST \
                    --url https://api.upwork.com/graphql \
                    --header 'Authorization: bearer oauth2v2_f5*************************' \
                    --header 'Content-Type: application/json' \
                    --header 'X-Upwork-API-TenantId: 470*************' \
                    --data '{"query":"query { \
                        organization { \
                        id \
                        childOrganizations { \
                        id \
                        name \
                      } \
                    } \
                  }"}'
                  

Flow and Supported Grants

For authenticating via OAuth 2.0 protocol, API requests MUST follow RFC 6749 specification.
At a basic level, the OAuth 2.0 authentication process involves the following steps:

1. Authorize the application using one of the available grants and obtain an Authorization code in Code Authorization Grant
2. Get an Access token in Code Authorization Grant and read it from the Implicit Grant workflow callback that follows the redirect in step#1

Once you receive an access token, you can use it to access protected resources. Use either the access_token parameter, or the Authorization header (recommended) with the Bearer schema and one of the supported grants. TTL for an access token is 24 hours; TTL for a refresh token is 2 weeks since its last usage.

<!DOCTYPE html>
            <html lang="en">
              <head>
                <meta charset="UTF-8" />
                <meta http-equiv="refresh" content="0;url='https://upwork.com/ab/messages/rooms/?code=b094053c2892cb819942e2d01e7237e7'" />
                <title>Redirecting to https://upwork.com/ab/messages/rooms/?code=b094053c2892cb819942e2d01e7237e7</title>
              </head>
              <body>
                Redirecting to <a href="https://upwork.com/ab/messages/rooms/?code=b094053c2892cb819942e2d01e7237e7">https://upwork.com/ab/messages/rooms/?code=b094053c2892cb819942e2d01e7237e7</a>.
              </body>
            </html>

            // Sample request
            curl --request POST \
              --url https://api.upwork.com/graphql \
              --header 'Content-Type: application/x-www-form-urlencoded' \
              --header 'Accept: application/json' \
              --data 'client_id=API_KEY_HERE&client_secret=KEY_SECRET_HERE&code=AUTHORIZATION_CODE_FROM_FIRST_STEP&grant_type=authorization_code&redirect_uri=CALLBACK_URL'
            
            // Authorization Code Grant - sample response
            {"access_token":"oauth2v2_cec*************************60","refresh_token":"oauth2v2_40d*************************40","token_type":"Bearer","expires_in":86400}
                    

/#access_token=abcdefghijklmnopqrstuvwxyz&expires_in=86399 // Implicit Grant

            {
              "access_token": "oauth2v2_584006c0ef4f69fd8278c7769da6ff43",
              "token_type": "Bearer",
              "expires_in": 86400
            }

            {
              "access_token": "oauth2v2_daedc8c79a4d5f80b88b2ce953772a0f",
              "refresh_token": "oauth2v2_e8ae4feb6b8d10693d8cff420351461a",
              "token_type": "Bearer",
              "expires_in": 86400
            }

Assigning permissions to Service Accounts

A Service Account is a user entity. By default, Service Accounts do not have any permissions. To access data by using a Service Account, you must have proper permissions associated with the Service Account.

To assign permissions to Service Accounts:

1. Log in to your Service Account.
2. Under Settings > Members & Permissions, locate the Service Account and update permissions according to the available options. You can set both team and company-level permissions depending on your needs. For more information, see Team Permissions.

Now, you are ready to leverage your service account to call Upwork’s APIs and perform specific operations.

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:

Python
PHP
Ruby
Java (+ Android, Maven, etc.)
JavaScript/NodeJS
Perl
GO

The following Tools are also available:

GQL Explorer - the tool allows you test GraphQL requests
API Center (Request new API Key) - allows you request a new application (API Key)
API Center (View existing API Keys) - manages all requested applications (API Keys)
API Subscriptions Management Tool - manages your GraphQL subscriptions
Terms of Use - here you can find terms, rules, and conditions of using Upwork API
Legacy REST API Docs - Documentation for our Legacy REST APIs can be viewed here. Note that these APIs are planned to be sunset and should only be used as a reference

Typical GraphQL services provide access to two types of requests: Queries and Mutations. The last can include more complicated structures in the request, like Arguments, Aliases, Fragments, Directives, and Variables. Queries are used to fetch the data, where Mutations are needed in order to modify server-side data. For more information, please follow Queries and Mutations section at graphql.org.

If the Upwork server fails while processing a GraphQL request, the system sends an error array response to the client. It is important to note that errors in GraphQL are handled differently from how we might be used to in ReST. While ReST endpoints return HTTP status codes in the error response, for example, 400 - Bad Request in case of malformed syntax, GraphQL always returns a 200 - OK status code, regardless of whether the operation succeeded or failed. Consequently, understanding how to decode error responses in GraphQL is crucial to troubleshooting potential operation failures.

Decoding error responses

GraphQL error arrays list all the errors that occurred while processing the API request. Additionally, they provide important information that helps you fix the problem or guide you on what to do next. Let’s take a closer look at what’s returned.

• Message: The error message that helps you understand if the operation succeeded or failed. For example, Validation error of type MissingFieldArgument.
• Locations: The exact location in the API request query that results in the error. For example, the line and column parameters in the response.
• Extensions: The type of error. For example, ValidationError.

Here is a sample code snippet of a GraphQL error response in Upwork:

          {
            "errors": [
              {
                "message": "Validation error of type MissingFieldArgument: Missing field argument stepUpVerificationId @ 'user/stepUpVerification'",
                "locations": [
                  {
                    "line": 3,
                    "column": 5
                  }
                ],
                "extensions": {
                  "classification": "ValidationError"
                }
              },
              {
                "message": "Validation error of type SubSelectionRequired: Sub selection required for type UserVerification of field stepUpVerification @ 'user/stepUpVerification'",
                "locations": [
                  {
                    "line": 3,
                    "column": 5
                  }
                ],
                "extensions": {
                  "classification": "ValidationError"
                }
              }
            ]
          }
              

As the generic status code in GraphQL is not intuitive, you must access the body of the error response to further understand the correct status of the operation.

Exceptions in GraphQL error types

Typically, GraphQL returns the HTTP status code 200 when the API operation fails at the upstream or data provider service layer. For example, if you do not have Oauth2 permissions or scopes to access an endpoint, the system displays the following error response

However, if the API operation fails at the GraphQL layer itself, the system returns the typical 5XX HTTP status codes, such as 500 - Internal Server Error if the server encounters an unexpected condition that prevents it from fulfilling the request. In these cases, you can rely on the status code to understand if the operation failed or succeeded.

Sample GraphQL API failure scenarios

          {
            user {
              id
              nid
              rid
              name
              email
            }
            organization {
              id
              rid
            }
          }
                

          {
            "errors": [
              {
                "message": "The client or authentication token doesn't have enough oauth2 permissions/scopes to access: [CurrentOrganization.id, CurrentOrganization.rid, CurrentUser.email, CurrentUser.id, CurrentUser.name, CurrentUser.nid, CurrentUser.rid, Query.organization, Query.user]."
              }
            ]
          }
                

          {
            user {
              companyFees(organizationId: null, input: { amount: "15" }) {
                amount
                fullAmount
                fees {
                  type
                  description
                  calculationDescription
                  rate
                  amount
                }
              }
            }
          }
                

          {
            "errors": [
              {
                "message": "Validation error of type NullValueForNonNullArgument: null value for non-null field argument organizationId @ 'user/companyFees'",
                "locations": [
                  {
                    "line": 3,
                    "column": 5
                  }
                ],
                "extensions": {
                  "classification": "ValidationError"
                }
              },
              {
                "message": "Validation error of type WrongType: argument 'organizationId' with value 'NullValue{}' must not be null @ 'user/companyFees'",
                "locations": [
                  {
                    "line": 3,
                    "column": 17
                  }
                ],
                "extensions": {
                  "classification": "ValidationError"
                }
              }
            ]
          }
          
                

          {
            user {
              stepUpVerification
            }
          }
                

          {
            "errors": [
              {
                "message": "Validation error of type MissingFieldArgument: Missing field argument stepUpVerificationId @ 'user/stepUpVerification'",
                "locations": [
                  {
                    "line": 3,
                    "column": 5
                  }
                ],
                "extensions": {
                  "classification": "ValidationError"
                }
              },
              {
                "message": "Validation error of type SubSelectionRequired: Sub selection required for type UserVerification of field stepUpVerification @ 'user/stepUpVerification'",
                "locations": [
                  {
                    "line": 3,
                    "column": 5
                  }
                ],
                "extensions": {
                  "classification": "ValidationError"
                }
              }
            ]
          }
                

Using GraphQL through Upwork SDK

Currently, Upwork supports GraphQL SDKs in the following languages:

Subscriptions in GraphQL

The Subscription feature allows clients to subscribe to specific events within the system. Once a subscribed event occurs, the system automatically sends a payload to the client’s designated webhook. This payload includes essential details about the event, such as the entity, action, and id associated with the event.

By utilizing this feature, clients can stay updated with real-time changes, ensuring they are always in sync with the events that matter most to their application or business. The subscription process is flexible and can be configured to trigger on various events, such as updates, creations, or other predefined actions.

Please, take into account that subscriptions feature is available only to clients. Once a subscription is created, it needs to be reviewed and approved by Upwork Team. Untill then, the subscription will remain in REVIEW state.

Key Components:

• Entity: Represents the object or resource associated with the event (e.g., "JP", "OFFER", "JA").
• Action: Describes the type of event or operation performed (e.g., "NEW", "UPDATE", "CANCELLED").
• ID: A unique identifier associated with the event, typically referencing a specific record or transaction.

When an event that the client has subscribed to is triggered, the system will send a payload to the client's webhook endpoint. This payload will include the entity name, action taken, and a unique identifier (ID) to allow for easy tracking and handling of the event.

Example Payload:

          {
              "entity": "OFFER",
              "action": "CREATE",
              "id": "123456789"
          }
                  

To manage your subscriptions and configure events easily, you can use our Subscription Management Tool. This tool allows you to view, create, and update your subscriptions through a user-friendly interface.

This ensures that clients receive the necessary data to process events in real-time, giving them complete control over how events are handled within their application. The flexibility to define custom webhooks and subscribe to a range of events provides a powerful way to integrate the system's activities with the client’s workflows.