API Documentation

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.

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

This page contains complete API reference of available Queries and Mutations, just use the navigation panel on the left.

Have a question? Visit us at:

  • Help Center
  • StackOverflow
  • Github
  • Community Forum
Contact

API Support

API Endpoints
# Endpoint:
https://api.upwork.com/graphql

Terminology

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 reports on their worked hours, 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 user 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. Legacy terms: engagement.

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.

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.

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.

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)

What are Scopes

Scopes are collections of permissions to access a specific set of APIs. They are usually grouped by domain and provide more control over sharing your account resources with different roles within your organization.

During the API key request process through the API Center, you are required to select the API Key scopes. At that point, your selection defines what APIs can be accessed by that specific API Key.

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.

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.

OAuth2 Basics

The OAuth 2.0 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 2.0 workflow process, visit the OAuth 2.0 protocol official site.

Client ID

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 in the API Center while logged into your Upwork account (select Key Type OAuth 2.0). You will receive a key (client_id) for each client identifier and client shared-secret you request.

Required X-Upwork-API-TenantId header

Each request requires the organization context. In order to specify on behalf of which context the request should be executed, you need to send X-Upwork-API-TenantId header. When the header is missing, the request will use the default organization of the user.

How X-Upwork-API-TenantId header can be used to set the Organization for the execution context

In order to get a value for the X-Upwork-API-TenantId header, you need company selector query.

Sample company selector query:

                  companySelector {
                    items {
                      title
                      organizationId
                    }
                  }
                  

The request with X-Upwork-API-TenantId would look like:

                  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
                      }
                    }
                  }"}'
                  

In this case query.organization and organization.childOrganizations will contain information about organization with id 470***********97.

Without the header query.organization will contain the information about 584***********76 which is the default organization for the user.

How the default Organization is selected when the header is not present

A default organization is one of the organizations that the user has access to. It is the same Organization that gets selected as the current Organization when a user logs in into the platform.

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.

Supported Grants


Authorization Code Grant

Authorization Code Grant is an OAuth 2.0 flow that enables you to obtain an access token. This grant is used to exchange an authorization code for an access token.

After you return to the client through the redirect URL, the application gets the authorization code from the URL and leverages it to request an access token.

To obtain an access token through the Authorization Code Grant, you must fulfill the following prerequisites and complete the steps thereafter:
  1. Prerequisites
  2. Obtain an authorization code
  3. Obtain an access token

Prerequisites

Data Description
Client ID

For each application you develop, you must obtain a client identifier key.

To get this value, access https://www.upwork.com/developer/keys/apply and log in by using your Upwork credentials

Notes:

  • You must be an enterprise client user or freelancer to request these details.
  • You must select Key Type as OAuth 2.0
  • For more information, see requesting an API key.

Client Secret

For each application you develop, you must obtain a client shared-secret key.

To get this value, access https://www.upwork.com/developer/keys/apply and log in by using your Upwork credentials

Notes:

  • You must be an enterprise client user or freelancer to request these details.
  • You must select Key Type as OAuth 2.0
  • For more information, see requesting an API key.

Callback URL

The URI to which Upwork redirects the browser after authentication. This is also known as redirect URI.

Notes:

Step 1. Obtaining an authorization code

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

Keep the refresh and access token private. If someone obtains your tokens, they could use them to access private user data.

Endpoint

GET  /ab/account-security/oauth2/authorize

Parameters

response_type
required, string

The corresponding grant type. Use code for Authorization Code Grant.
client_id
required, string

Your Client ID.
redirect_uri
required, string

Redirect URI, must be equal or similar to the callback specified in the key settings.


Returns

Returns the code.
<!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>

Here, https://upwork.com/ab/messages/rooms/ is the Callback URL and b094053c2892cb819942e2d01e7237e7 is the authorization code.

Step 2. Obtaining an access token

Keep the access token private. If someone obtains your token, they could use it to access private user data.

Endpoint

POST  /api/v3/oauth2/token

Parameters

grant_type
required, string

Grant type. To get a token right after authorization, use authorization_code.
client_id
required, string

Your Client ID.
client_secret
required, string

Your Client Secret.
code
required, string

Authorization code received during the authorization request.
redirect_uri
required, string

Redirect URI, must be equal or similar to the callback specified in the key settings.


Returns

Returns the access token and its TTL. Example:
/#access_token=abcdefghijklmnopqrstuvwxyz&expires_in=86399 // Authorization Code Grant

Implicit Grant

Implicit Grant is an OAuth 2.0 flow that enables you to obtain an access token without obtaining an authorization code.

When the system redirects you to the client through the redirect URL, the application appends the access token in the URI. Therefore, unlike the Authorization Code Grant, you do not need to leverage the temporary code to obtain an access token.

To obtain an access token through the Implicit Grant, you must fulfill the following prerequisites and complete the steps thereafter:
  1. Prerequisites
  2. Obtain an access token

Prerequisites

Data Description
Client ID

For each application you develop, you must obtain a client identifier key.

To get this value, access https://www.upwork.com/developer/keys/apply and log in by using your Upwork credentials.

Notes:

  • You must be an enterprise client user or freelancer to request these details.
  • You must select Key Type as OAuth 2.0
  • For more information, see requesting an API key.

Client Secret

For each application you develop, you must obtain a client shared-secret key.

To get this value, access https://www.upwork.com/developer/keys/apply and log in by using your Upwork credentials.

Notes:

  • You must be an enterprise client user or freelancer to request these details.
  • You must select Key Type as OAuth 2.0
  • For more information, see requesting an API key.

Callback URL

The URI to which Upwork redirects the browser after authentication. This is also known as redirect URI.

Notes:

Step 1. Obtaining an access token

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

Keep the access token private. If someone obtains your token, they could use it to access private user data.

Endpoint

GET  /ab/account-security/oauth2/authorize

Parameters

response_type
required, string

The corresponding grant type. Use token for Implicit Grant.
client_id
required, string

Your Client ID.
client_secret
required, string

Your Client Secret.
redirect_uri
required, string

Redirect URI, must be equal or similar to the callback specified in the key settings.


Returns

Returns the access token and its TTL. Example:
/#access_token=abcdefghijklmnopqrstuvwxyz&expires_in=86399 // Implicit Grant

Client Credentials Grant

Client Credentials Grant is an OAuth 2.0 flow that enables you to obtain an access token in server-to-server and client-to-server scenarios. Although users are involved in this flow, you can use the access token outside the context of a user. For example, you can leverage the access token to access the client's resources.

To obtain an access token through the Client Credentials Grant, you must fulfill the following prerequisites and complete the steps thereafter:
  1. Prerequisites
  2. Obtain an access token

Client Credentials grant is only available to Enterprise consumers

Prerequisites

Data Description
Client ID

For each application you develop, you must obtain a client identifier key.

To get this value, access https://www.upwork.com/developer/keys/apply and log in by using your Upwork credentials.

Notes:

  • You must be an enterprise client user or freelancer to request these details.
  • You must select Key Type as OAuth 2.0
  • For more information, see requesting an API key.

Client Secret

For each application you develop, you must obtain a client shared-secret key.

To get this value, access https://www.upwork.com/developer/keys/apply and log in by using your Upwork credentials.

Notes:

  • You must be an enterprise client user or freelancer to request these details.
  • You must select Key Type as OAuth 2.0
  • For more information, see requesting an API key.

Step 1. Obtaining an access token

Keep the access token private. If someone obtains your token, they could use it to access private user data.

Endpoint

POST  /api/v3/oauth2/token

Parameters

grant_type
required, string

Grant type. To get an access token for the client credentials grant, use client_credentials.
client_id
required, string

Your Client ID.
client_secret
required, string

Your Client Secret.


Returns

Returns the access token and its TTL. Example:
            {
              "access_token": "oauth2v2_584006c0ef4f69fd8278c7769da6ff43",
              "token_type": "Bearer",
              "expires_in": 86400
            }

Refresh Token Grant Type

Refresh Token Grant Type is an OAuth 2.0 flow that enables you to exchange a refresh token for an access token when the access token has expired. Therefore, you can continue to have a valid access token without further interaction with the user.

To obtain an access token through the Refresh Token Grant Type, you must fulfill the following prerequisites and complete the steps thereafter:
  1. Prerequisites
  2. Obtain an access token

Prerequisites

Data Description
Client ID

For each application you develop, you must obtain a client identifier key.

To get this value, access https://www.upwork.com/developer/keys/apply and log in by using your Upwork credentials.

Notes:

  • You must be an enterprise client user or freelancer to request these details.
  • You must select Key Type as OAuth 2.0
  • For more information, see requesting an API key.

Client Secret

For each application you develop, you must obtain a client shared-secret key.

To get this value, access https://www.upwork.com/developer/keys/apply and log in by using your Upwork credentials.

Notes:

  • You must be an enterprise client user or freelancer to request these details.
  • You must select Key Type as OAuth 2.0
  • For more information, see requesting an API key.

Step 1. Obtaining an access token

Keep the refresh token private. If someone obtains your token, they could use it to access private user data.

Endpoint

POST  /api/v3/oauth2/token

Parameters

grant_type
required, string

Grant type. To refresh an existing token, having a valid refresh token, use refresh_token.
client_id
required, string

Your Client ID.
client_secret
required, string

Your Client Secret.
refresh_token
required, string

A valid refresh token.


Returns

If you authenticated previously and have a working refresh token, this call returns the refreshed tokens and the TTL of the access token.
            {
              "access_token": "oauth2v2_daedc8c79a4d5f80b88b2ce953772a0f",
              "refresh_token": "oauth2v2_e8ae4feb6b8d10693d8cff420351461a",
              "token_type": "Bearer",
              "expires_in": 86400
            }

Service accounts

Service accounts are specific to a service or application and are designed to run applications. Service accounts help you communicate with multiple applications, such as web servers and databases. Unlike user accounts, service accounts are used by system services, for example, web servers, mail transport agents, and databases.

Service accounts are useful when you need to fetch information. For example, you can use service accounts to get information about multiple users in a company. However, you must not use service accounts to perform write operations.

Note that service accounts are available only for enterprise accounts in Upwork.

Prerequisites for using a Service Account in Upwork

After Upwork creates the Client Credentials key and associates it with a service account, you can assign appropriate scopes and permissions to the service account.

Requesting a Client Credentials key

To apply for the Client Credentials key:

  1. Go to https://www.upwork.com/developer/keys/apply and provide the requested information about your application.
    For more information, see the Getting Started section.
  2. Select the I want to create a Client Credential key for Service Account check box.
  3. Select the relevant scopes. For more information, see scopes.
  4. Save the changes.

Upwork creates the Client Credentials key and displays the values in a pop-up window. In addition, you can view your key at https://www.upwork.com/developer/keys/.

Upwork also creates a Service Account and associates the account with the Client Credentials key. Thereafter, if you perform any actions by using the key, the system actually performs such actions on behalf of the Service Account and not your user account.

Assigning Scopes to Service Accounts

Scopes are collections of permissions to access a specific set of APIs. They are usually grouped by domain and provide more control over sharing your account resources with different roles within your organization.

While applying for the Client Credentials key, you can select the relevant Scopes. These Scopes define the APIs that you can access by using the same key. For more information about Scopes, see What are Scopes.

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.

Authorization Request

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

Keep the refresh and access token private. If someone obtains your tokens, they could use them to access private user data.

Endpoint

GET  /ab/account-security/oauth2/authorize

Parameters

response_type
required, string

The corresponding Grant Type. Use `code` for Authorization Code Grant and `token` for Implicit Grant.
Valid values: code, token
client_id
required, string

Your Client ID.
redirect_url
required, string

The callback URL.


Returns

Returns a code for the Authorization Code Grant or an access token for the Implicit Grant. Example:
/#access_token=abcdefghijklmnopqrstuvwxyz&expires_in=86399 // Implicit Grant

Access Token Request

Keep the refresh and access token private. If someone obtains your tokens, they could use them to access private user data.

Endpoint

POST  /api/v3/oauth2/token

Parameters

grant_type
required, string

Grant type. To get a token right after authorization, use `authorization_code`. To refresh an existing token, having a valid `refresh token`, use `refresh_token`.
To get an access token for the client credentials grant, use `client_credentials`.
Valid values: authorization_code, refresh_token, client_credentials
client_id
required, string

Your Client ID.
client_secret
required, string

Your Client Secret.
code
conditionally required, string

Authorization code received during the authorization request. Required for `authorization_code` grant.
redirect_uri
conditionally required, string

Redirect URI, must be equal or similar to the callback specified in the key settings. Required for `authorization_code` grant.
refresh_token
conditionally required, string

A valid refresh token. Required for `refresh_token` grant.


Returns

If the authorization is successful, this call returns the tokens and the TTL of the access token.

Refresh Token Request

The Access Token request should be used with the proper grant type, which is "refresh_token", in order to refresh the token.

Keep the refresh and access token private. If someone obtains your tokens, they could use them to access private user data.

Returns

If you authenticated previously and have a working refresh token, this call returns the refreshed tokens and the TTL of the access token.

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:

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

REST to GraphQL examples

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

Messages

GraphQL OAuth2 scopes:

Name Description
Messaging - Read-Only Access Grants read-only access to rooms and messages
Messaging - Read and Write Access Grants read/write access to rooms and messages

Retrieve rooms information

Gets the rooms for the current user and organization

REST
GET  /api/messages/v3/{company_id}/rooms.{format} 
GraphQL
query roomList(
  $filter: RoomFilter,
  $pagination: Pagination,
  $sortOrder: SortOrder
) {
  roomList(
    filter: $filter,
    pagination: $pagination,
    sortOrder: $sortOrder
  ) {
    totalCount
    pageInfo {
      endCursor
      hasNextPage
    }
    edges {
      node {
        numUnread
        numUnreadMentions
        numUsers
        favorite
        latestStory {
          createdDateTime
          updatedDateTime
        }
        topic
        roomType
        id
        roomName
        organization {
          id
          legacyId
        }
        roomUsers {
          user {
            id
          }
          organization {
            id
          }
          role
        }
        creator {
          user {
            id
            nid
            name
          }
        }
        createdAtDateTime
        public
        owner {
          user {
            id
          }
        }
      }
    }
  }
}
Variables
{
  "filter": {
    "roomType_eq": "ALL",
    "roomPrivacy_eq": "ALL",
    "subscribed_eq": false,
    "activeSince_eq": "xyz789",
    "includeFavorites_eq": false,
    "includeUnreadIfActive_eq": false,
    "unreadRoomsOnly_eq": false,
    "local_eq": "abc123",
    "includeHidden_eq": true,
    "objectReferenceId_eq": "4",
    "roomCategory_eq": "FAVORITES"
  },
  "pagination": {"after": "abc123", "first": 987},
  "sortOrder": "ASC"
}

Fields:

REST Field GraphQL Path Description
rooms.roomId roomList.edges.node.id The ID of the room
rooms.orgId roomList.edges.node.organization.id The ID of the org that the room belongs to
rooms.roomName roomList.edges.node.name The name of the room
rooms.roomType roomList.edges.node.roomType The room type
rooms.topic roomList.edges.node.topic The topic of the room
rooms.numUnread roomList.edges.node.numUnread The number of unread messages in the room for the current user
rooms.numUnreadMentions roomList.edges.node.numUnreadMentions The number of unread messages with @ mentions in the room for the current user
rooms.numUsers roomList.edges.node.numUsers The number of users in the room
rooms.isFavorite roomList.edges.node.favorite Indicates whether the user marked the room as a favorite or not
rooms.latestStory.created roomList.edges.node.latestStory.createdDateTime The creation timestamp of the story
rooms.latestStory.updated roomList.edges.node.latestStory.updatedDateTime The update timestamp of the story
rooms.users.userId roomList.edges.node.roomUsers.user.id The ID of the user
rooms.users.orgId roomList.edges.node.roomUsers.organization.id The ID of the org (company context) that the user is subscribed with
rooms.users.role roomList.edges.node.roomUsers.user.role Role of the user. Returned only if returnUserRoles is set
rooms.cursor roomList.edge.cursor The ID of the last room returned in the call
rooms.total roomList.totalCount The total number of matching rooms, for paging purposes
rooms.appId roomList.edges.node.vendorProposal.id Unique application ID

Get a specific room information

Gets a specific room information

REST
GET  /api/messages/v3/{company_user_id}/rooms/{room_id}.{format} 
GraphQL
query room($roomId: ID!) {
  room(id: $roomId) {
    id
    organization {
      id
    }
    roomName
    roomType
    topic
    lastVisitedDateTime
    lastReadDateTime
    favorite
    readOnly
    hidden
    roomUsers {
      user {
        id
      }
      organization {
        id
      }
      role
    }
    stories {
      totalCount
      pageInfo {
        endCursor
      }
      edges {
        node {
          id
          createdDateTime
          updatedDateTime
          user {
            id
          }
          message
          systemStory
        }
      }
    }
  }
}
Variables
{"roomId": 4}

Fields:

REST Field GraphQL Path Description
roomId room.id The ID of the room
orgId room.organization.id The ID of the org that the room belongs to
roomName room.roomName The name of the room
roomType room.roomType The room type
topic room.topic The topic of the room
lastReadTimestamp room.lastVisitedDateTime Timestamp of the last time the user accessed the room
recentTimestamp room.lastReadDateTime Timestamp of the latest activity in the room for sorting purposes
isFavorite room.favorite Indicates whether the user marked the room as favorite or not
isReadOnly room.readOnly Indicates whether the room is archived or not
isHidden room.hidden Indicates whether the room marked as hidden/archived or not
roleI room.roomUsers.role Indicates a role of the user in the particular room
users.userId room.roomUsers.user.id The ID of the user
users.orgId room.roomUsers.organization.id The ID of the org that the user is subscribed with
users.role room.roomUsers.role The role of the user. Returned only if returnUserRoles is set
stories.stories.storyId room.stories.edge.node.id Story ID
stories.stories.created room.stories.edge.node.createdDateTime Indicates when the message was created
stories.stories.updated room.stories.edge.node.updatedDateTime Indicates when the message was updated
stories.stories.userId room.stories.edge.node.user.id ID of a user who posted the message
stories.stories.message room.stories.edge.node.message Message
stories.stories.isSystemStory room.stories.edge.node.systemStory Flag indicates whether the message is system
stories.cursor room.stories.edge.cursor Current position of a cursor
stories.total room.stories.totalCount Total number of messages

Get messages from the room

Gets messages/stories from a specific room

REST
GET  /api/messages/v3/{company_user_id}/rooms/{room_id}/stories.{format} 
GraphQL
query RoomStories($roomId: ID!) {
  roomStories(filter: {roomId_eq: $roomId}) {
    totalCount
    edges {
      node {
        id
        message
      }
    }
  }
}
Variables
{"roomId": "4"}

Fields:

REST Field GraphQL Path Description
stories.storyId roomStories.edge.node.id Story ID
stories.created roomStories.edge.node.createdDateTime Indicates when the message was created
stories.updated roomStories.edge.node.updatedDateTime Indicates when the message was updated
stories.userId roomStories.edge.node.user.id ID of a user who posted the message
stories.message roomStories.edge.node.message Message
stories.isSystemStory roomStories.edge.node.systemStory Flag indicates whether the message is system
stories.cursor roomStories.edge.cursor Current position of a cursor
stories.total roomStories.totalCount Total number of messages

Get a specific room by offer ID

Gets the room information for the interview room with the offerId passed on the URL

REST
GET  /api/messages/v3/{company_user_id}/rooms/offers/{offer_id}.{format} 
GraphQL
query offerRoom($offerId: ID!) {
  offerRoom(id: $offerId) {
    id
    roomName
  }
}
Variables
{"offerId": "4"}

Fields:

REST Field GraphQL Path Description
roomId offerRoom.id The ID of the room
orgId offerRoom.organization.id The ID of the org that the room belongs to
roomName offerRoom.roomName The name of the room
roomType offerRoom.roomType The room type
topic offerRoom.topic The topic of the room
lastReadTimestamp offerRoom.lastVisitedDateTime Timestamp of the last time the user accessed the room
recentTimestamp offerRoom.lastReadDateTime Timestamp of the latest activity in the room for sorting purposes
isFavorite offerRoom.favorite Indicates whether the user marked the room as favorite or not
isReadOnly offerRoom.readOnly Indicates whether the room is archived or not
isHidden offerRoom.hidden Indicates whether the room marked as hidden/archived or not
roleI offerRoom.roomUsers.role Indicates a role of the user in the particular room
users.userId offerRoom.roomUsers.user.id The ID of the user
users.orgId offerRoom.roomUsers.organization.id The ID of the org that the user is subscribed with
users.role offerRoom.roomUsers.role The role of the user. Returned only if returnUserRoles is set
stories.stories.storyId offerRoom.stories.edge.node.id Story ID
stories.stories.created offerRoom.stories.edge.node.createdDateTime Indicates when the message was created
stories.stories.updated offerRoom.stories.edge.node.updatedDateTime Indicates when the message was updated
stories.stories.userId offerRoom.stories.edge.node.user.id ID of a user who posted the message
stories.stories.message offerRoom.stories.edge.node.message Message
stories.stories.isSystemStory offerRoom.stories.edge.node.systemStory Flag indicates whether the message is system
stories.cursor offerRoom.stories.edge.cursor Current position of a cursor
stories.total offerRoom.stories.totalCount Total number of messages

Get a specific room by application ID

Gets the room information for the interview room with the applicationId passed on the URL

REST
GET  /api/messages/v3/{company_user_id}/rooms/applications/{application_id}.{format} 
GraphQL
query proposalRoom($vendorProposalId: ID!) {
  proposalRoom(id: $vendorProposalId) {
    id
    roomName
  }
}
Variables
{"vendorProposalId": "4"}

Fields:

REST Field GraphQL Path Description
roomId proposalRoom.id The ID of the room
orgId proposalRoom.organization.id The ID of the org that the room belongs to
roomName proposalRoom.roomName The name of the room
roomType proposalRoom.roomType The room type
topic proposalRoom.topic The topic of the room
lastReadTimestamp proposalRoom.lastVisitedDateTime Timestamp of the last time the user accessed the room
recentTimestamp proposalRoom.lastReadDateTime Timestamp of the latest activity in the room for sorting purposes
isFavorite proposalRoom.favorite Indicates whether the user marked the room as favorite or not
isReadOnly proposalRoom.readOnly Indicates whether the room is archived or not
isHidden proposalRoom.hidden Indicates whether the room marked as hidden/archived or not
roleI proposalRoom.roomUsers.role Indicates a role of the user in the particular room
users.userId proposalRoom.roomUsers.user.id The ID of the user
users.orgId proposalRoom.roomUsers.organization.id The ID of the org that the user is subscribed with
users.role proposalRoom.roomUsers.role The role of the user. Returned only if returnUserRoles is set
stories.stories.storyId proposalRoom.stories.edge.node.id Story ID
stories.stories.created proposalRoom.stories.edge.node.createdDateTime Indicates when the message was created
stories.stories.updated proposalRoom.stories.edge.node.updatedDateTime Indicates when the message was updated
stories.stories.userId proposalRoom.stories.edge.node.user.id ID of a user who posted the message
stories.stories.message proposalRoom.stories.edge.node.message Message
stories.stories.isSystemStory proposalRoom.stories.edge.node.systemStory Flag indicates whether the message is system
stories.cursor proposalRoom.stories.edge.cursor Current position of a cursor
stories.total proposalRoom.stories.totalCount Total number of messages

Get a specific room by contract ID

Gets the room information for the interview room with the contractId passed on the URL

REST
GET  /api/messages/v3/{company_user_id}/rooms/contracts/{contract_id}.{format} 
GraphQL
query contractRoom($contractId: ID!) {
  contractRoom(id: $contractId) {
    id
    roomName
  }
}
Variables
{"contractId": 4}

Fields:

REST Field GraphQL Path Description
roomId contractRoom.id The ID of the room
orgId contractRoom.organization.id The ID of the org that the room belongs to
roomName contractRoom.roomName The name of the room
roomType contractRoom.roomType The room type
topic contractRoom.topic The topic of the room
lastReadTimestamp contractRoom.lastVisitedDateTime Timestamp of the last time the user accessed the room
recentTimestamp contractRoom.lastReadDateTime Timestamp of the latest activity in the room for sorting purposes
isFavorite contractRoom.favorite Indicates whether the user marked the room as favorite or not
isReadOnly contractRoom.readOnly Indicates whether the room is archived or not
isHidden contractRoom.hidden Indicates whether the room marked as hidden/archived or not
roleI contractRoom.roomUsers.role Indicates a role of the user in the particular room
users.userId contractRoom.roomUsers.user.id The ID of the user
users.orgId contractRoom.roomUsers.organization.id The ID of the org that the user is subscribed with
users.role contractRoom.roomUsers.role The role of the user. Returned only if returnUserRoles is set
stories.stories.storyId contractRoom.stories.edge.node.id Story ID
stories.stories.created contractRoom.stories.edge.node.createdDateTime Indicates when the message was created
stories.stories.updated contractRoom.stories.edge.node.updatedDateTime Indicates when the message was updated
stories.stories.userId contractRoom.stories.edge.node.user.id ID of a user who posted the message
stories.stories.message contractRoom.stories.edge.node.message Message
stories.stories.isSystemStory contractRoom.stories.edge.node.systemStory Flag indicates whether the message is system
stories.cursor contractRoom.stories.edge.cursor Current position of a cursor
stories.total contractRoom.stories.totalCount Total number of messages

Create a new room

Creates a new room. Note that 1-1 rooms must be passed in a single user in the users array. Both users are created with `admin` role in the room and the role you pass is ignored (there is no owner)

REST
POST  /api/messages/v3/{company_user_id}/rooms.{format} 
GraphQL
mutation createRoom($roomName: String!, $publicRoom: Boolean!, $roomType: RoomType!, $readOnly: Boolean!, $systemRoom: Boolean!) {
  createRoom(
    input: {roomName: $roomName, public: $publicRoom, roomType: $roomType, readOnly: $readOnly, systemRoom: $systemRoom}
  ) {
    id
    roomName
  }
}
Variables
{
  "roomName": "abc123",
  "publicRoom": true,
  "roomType": "ONE_ON_ONE",
  "readOnly": false,
  "systemRoom": false
}

Send a message to a room

Adds a new story to the given room

REST
POST  /api/messages/v3/{company_user_id}/rooms/{room_id}/stories.{format} 
GraphQL
mutation createRoomStory($roomId: ID!, $actionType: String!, $sourceClient: String!) {
  createRoomStory(
    input: {roomId: $roomId, actionType: $actionType, sourceClient: $sourceClient}
  ) {
    id
    message
  }
}
Variables
{"roomId": 4, "actionType": "xyz789", "sourceClient": "xyz789"}

Send a message to a batch of rooms

Adds a new story to the list of the given rooms

REST
POST  /api/messages/v3/{company_user_id}/stories/batch.{format} 
GraphQL
Same as sending a single message, but multiple mutations in one request

Update a room settings

Updates a room settings

REST
PUT  /api/messages/v3/{company_user_id}/rooms/{room_id}/users/{user_id}.{format} 
GraphQL
mutation updateRoom($roomId: ID!, $topic: String!) {
  updateRoom(input: {roomId: $roomId, topic: $topic}) {
    id
    roomName
  }
}
Variables
{"roomId": 4, "topic": "abc123"}

Archive or rename a room

Updates the metadata of an existing room and archives it

REST
PUT  /api/messages/v3/{company_user_id}/rooms/{room_id}.{format} 
GraphQL
mutation archiveRoom($roomId: ID!) {
  archiveRoom(roomId: $roomId) {
    id
    roomName
  }
}
Variables
{"roomId": 4}

Contracts & Offers

Fields:

REST Field GraphQL Path Notes
buyer_team__id No direct match Possible alternative: organization/clientOffers/edges/node/team/id
buyer_team__reference organization/clientOffers/edges/node/team/rid
category_uid organization/clientOffers/edges/node/contract/jobCategory/id
cj_job_application_uid No direct match
created_time organization/clientOffers/edges/node/contract/createdDateTime
dev_recno_ciphertext No direct match
downsample_screenshots No direct match
engagement_end_date organization/clientOffers/edges/node/contract/endDateTime
engagement_end_ts organization/clientOffers/edges/node/contract/endDateTime
engagement_job_type organization/clientOffers/edges/node/contract/contractType
engagement_start_date organization/clientOffers/edges/node/contract/startDateTime
engagement_start_ts organization/clientOffers/edges/node/contract/startDateTime
engagement_title organization/clientOffers/edges/node/contract/title
estimated_duration organization/clientOffers/edges/node/contract/estimatedDuration Deprecated
estimated_duration_id No direct match
first_engagement_start_ts organization/clientOffers/edges/node/contract/firstContractStartDateTime
freelancer_country organization/clientOffers/edges/node/contract/freelancer/countryDetails/name
freelancer_title No direct match
hide_screenshots organization/clientOffers/edges/node/contract/hideScreenshots Deprecated
hourly_charge_rate organization/clientOffers/edges/node/contract/hourlyChargeRate/rawValue
is_fls No direct match
isfp2 organization/clientOffers/edges/node/contract/contractType
is_last organization/clientOffers/edges/node/contract/last
is_paused organization/clientOffers/edges/node/contract/paused
job__reference organization/clientOffers/edges/node/contract/offer/job/id
job__title organization/clientOffers/edges/node/contract/job/content/title
job_application_ref organization/clientOffers/edges/node/contract/offer/vendorProposal/id
job_posting_uid organization/clientOffers/edges/node/contract/job/
job_ref_ciphertext No direct match
manual_time_allowed organization/clientOffers/edges/node/contract/manualTimeAllowed
modified_time organization/clientOffers/edges/node/contract/modifiedDateTime
offer__reference No direct match
offer_id organization/clientOffers/edges/node/contract/offer/id
parent_reference No direct match Possible alternative: organization/clientOffers/edges/node/contract/offer/id
provider__has_agency organization/clientOffers/edges/node/contract/hasAgency
provider__id organization/clientOffers/edges/node/contract/freelancer/user/nid
provider__reference organization/clientOffers/edges/node/contract/freelancer/user/rid
provider_team__id No direct match Possible alternative: organization/clientOffers/edges/node/contract/offer/agency/id
provider_team__reference No direct match Possible alternative: organization/clientOffers/edges/node/contract/offer/agency/rid
reference organization/clientOffers/edges/node/contract/id
status organization/clientOffers/edges/node/contract/status
weekly_hours_limit organization/clientOffers/edges/node/contract/weeklyHoursLimit
weekly_salary_charge_amount organization/clientOffers/edges/node/contract/weeklyChargeAmount
weekly_stipend_hours organization/clientOffers/edges/node/contract/weeklyStipendHours

GraphQL OAuth2 scopes:

Name Description
Offer - Read-Only Access Grants read-only access to offer's information
Offer - Read And Write Access Grants read/write access to offers

List engagements

This call returns engagement(s) based on the parameters supplied in the API call

REST
GET  /api/hr/v2/engagements
GET /api/hr/v2/engagements.{format}
GraphQL
query organization {
  organization {
    id
    clientOffers(pagination: {after: "98", first: 1}) {
      totalCount
      edges {
        cursor
        node {
          id
          team {
            id
            rid
            legacyId
            name
            type
            legacyType
          }
          contract {
            offer {
              id
              offerTerms {
                fixedPriceTerm {
                  budget {
                    rawValue
                  }
                }
              }
              agencyOffers {
                totalCount
                edges
                pageInfo
              }
            }
            clientProposal {
              id
            }
            contractType
            createdDateTime
            endDateTime
            estimatedDuration {
              id
            }
            firstContractStartDateTime
            freelancer {
              user {
                id
                nid
                rid
                ciphertext
              }
              countryDetails {
                id
                name
              }
            }
            hasAgency
            hideScreenshots
            hourlyChargeRate {
              rawValue
            }
            id
            job {
              id
              classification {
                category {
                  id
                  type
                }
              }
              content {
                title
              }
            }
            jobCategories {
              id
              name
              selectedCategories
            }
            last
            manualTimeAllowed
            milestones {
              id
            }
            modifiedDateTime
            offer {
              id
            }
            paused
            startDateTime
            status
            suspended
            title
            weeklyChargeAmount {
              rawValue
            }
            weeklyHoursLimit
            weeklyStipendHours
          }
        }
      }
    }
  }
}

Get engagement

This call retrieves details about a specific engagement.

REST
GET  /api/hr/v2/engagements/{engagement_reference}.{format} 
GraphQL
query contract($id: ID!) {
  contract(id: $id) {
    id
    offer {
      id
      offerTerms {
        fixedPriceTerm {
          budget {
            rawValue
          }
        }
      }
    }
    clientProposal {
      id
    }
    contractType
    createdDateTime
    endDateTime
    estimatedDuration {
      id
    }
    firstContractStartDateTime
    freelancer {
      user {
        id
        nid
        rid
        ciphertext
      }
      countryDetails {
        id
        name
      }
    }
    hasAgency
    hideScreenshots
    hourlyChargeRate {
      rawValue
    }
    id
    job {
      id
      classification {
        category {
          id
          type
        }
      }
      content {
        title
      }
    }
    last
    manualTimeAllowed
    milestones {
      id
    }
    modifiedDateTime
    offer {
      id
    }
    paused
    startDateTime
    status
    suspended
    title
    weeklyChargeAmount {
      rawValue
    }
    weeklyHoursLimit
    weeklyStipendHours
  }
}
Variables
{"id": 4}


Payments

GraphQL OAuth2 scopes:

Name Description
Payments - Read and Write Access Grants read and write access to payment activities

Make custom payment

This call is designed for making custom payments for a specific team and engagement in that team

REST
POST  /api/hr/v2/teams/{team_reference}/adjustments.{format} 
GraphQL
mutation sendCustomPayment(
  $contractId: ID!
  $amount: Float!
  $comment: String!
  $notes: String!
  $allowSubsequent: Boolean
) {
  sendCustomPayment(input: {
    contractId: $contractId
    amount: $amount
    comment: $comment
    notes: $notes
    allowSubsequent: $allowSubsequent
  }) {
    invoiceId
  }
}
Variables
{
  "contractId": 4,
  "amount": 123.45,
  "comment": "xyz789",
  "notes": "xyz789",
  "allowSubsequent": false
}

Fields:

REST Field GraphQL Path
reference mutation.sendCustomPayment.invoiceId

Public Profiles

GraphQL OAuth2 scopes:

Name Description
Freelancer Profile - Read And Write Access Grants read/write access to freelancer profile

Search for Freelancers

The search parameters include the options available on the site and additional options to configure the format of your results.

REST
GET  /api/profiles/v2/search/providers.{format} 
GraphQL
{
  search {
    searchFreelancerPublicProfile(
      request: {
        paging: $paging,
        userQuery: $userQuery,
        occupationUid: $occupationUid,
        title: $title,
        countries: $countries,
        states: $states,
        cities: $cities,
        hourlyRate: $hourlyRate,
        jobSuccessScore: $jobSuccessScore,
        totalJobs: $totalJobs,
        topRated: $topRated,
        risingTalent: $risingTalent,
        hasPortrait100: $hasPortrait100,
        skillsNames: $skillsNames,
        skillsUids: $skillsUids,
        vemSkills: $vemSkills,
        type: $type,
        addAgencyPreview: $addAgencyPreview,
        agencySearch: $agencySearch,
        publicVisibilityOnly: $publicVisibilityOnly
      }
    ) {
      profiles {
        profile {
          identity {
            id
            ciphertext
          }
          profileAggregates {
            lastWorkedOn
            topRatedStatus
            totalJobs
            totalFeedback
            totalHourlyJobs
            totalFixedJobs
            adjustedCategoryScores {
              averageCategoryScore
            }
          }
          personalData {
            portrait {
              portrait
            }
            firstName
            lastName
            title
            description
            location {
              country
              state
              city
            }
          }
          specializedProfilesSkills {
            skills {
              ontologySkill {
                skill {
                  id
                }
                skillUid
              }
            }
          }
        }
      }
    }
  }
}
Variables
{
  "paging": {"start": 123, "rows": 123},
  "userQuery": "xyz789",
  "occupationUid": "xyz789",
  "title": "xyz789",
  "countries": ["abc123"],
  "states": ["xyz789"],
  "cities": ["xyz789"],
  "hourlyRate": {"min": 987.65, "max": 987.65},
  "jobSuccessScore": {"min": 987.65, "max": 987.65},
  "totalJobs": {"min": 123, "max": 123},
  "topRated": false,
  "risingTalent": false,
  "hasPortrait100": true,
  "skillsNames": ["abc123"],
  "skillsUids": ["abc123"],
  "vemSkills": [{"skill": "abc123", "weight": 987.65}],
  "type": "Agency",
  "addAgencyPreview": false,
  "agencySearch": false,
  "publicVisibilityOnly": false
}

Fields:

REST Field GraphQL Path Description
q userQuery The search query. At least one of the `q`, `title`, `skill` parameters should be specified.
title title Searches for the title in the freelancer's profile. At least one of the `q`, `title`, `skill` parameters should be specified.
skills skillsNames Searches for skills of freelancer's profile. At least one of the `q`, `title`, `skill` parameters should be specified.
groups Searches for groups in the freelancer's profile. The freelancer must be a member of the group provided.
tests Searches for tests in the freelancer's profile.
tests_top_10 Searches for freelancers that are in the top 10 of the test.
tests_top_30 Searches for freelancers that are in the top 30 of the test.
category2 The category (V2) of the freelancer's profile. Use Metadata resource to get it. You can get it via Metadata Category (v2) resource.
subcategory2 The subcategory of the job according to the list of Categories 2.0. Example: `Web & Mobile Development`. You can get it via Metadata Category (v2) resource.
region countries Searches for profiles of freelancers who live in the region provided. Valid values are provided by Metadata Regions resource. Example: `Latin America`.
feedback Searches for freelancers with specific feedback score. Single values such as `3` or `3,4` (comma-separated values results in OR queries) and ranges such as `[3 TO 4]` are valid.
rate A number or range used to filter the search by freelancer's profile rate. Single values such as `20` or `20,30` (comma-separated values result in `OR` queries) and ranges such as `[20 TO 40]` are valid.
topRated Note we have topRated Boolean
hours Searches for profiles of freelancers who have worked the number of hours provided. Single values such as `20` or `20,30` (comma-separated values result in `OR` queries) and ranges such as `[20 TO 40]` are valid.
recent_hours Searches for profiles of freelancers who have recently worked the number of hours provided. Single values such as `20` or `20,30` (comma-separated values result to `OR` queries) and ranges such as `[20 TO 40]` are valid.
last_activity The date of the last time the freelancer worked. The value should be formatted according to ISO 8601 date syntax with hours always set at 00:00:00.000. Example: `2013-01-04T00:00:00.000Z`.
english_skill The freelancer's English skills assessment result. Valid values: 0, 1, 2, 3, 4, 5
is_odesk_ready Defines if the freelancer is Upwork ready or not. Valid values: 0, 1
profile_type type The freelancer type. Valid values: Agency, Independent
include_entities If set to `1` the data in the response will only contain a profile IDs array. Valid values: 0, 1
profile_access publicVisibilityOnly The access type of the profile. Valid values: auth, public
nss100 jobSuccessScore Job success score. Example: value `[0.8 TO *]` returns freelancers with job success score more than 0.8 (80%).
paging Pagination, formed as `$offset;$count`. Page size is restricted to be <= 50. Example: page=100;30.

Get brief profile summary

Read and search profiles of contractors and jobs, and get lists of public metadata

REST
GET  /api/profiles/v1/providers/{profile_key}/brief.{format} 
GraphQL
query getFreelancerProfile($profileKey: String!) {
  freelancerProfileByProfileKey(profileKey: $profileKey) {
    aggregates {
      ...FreelancerProfileAggregatesFragment
    }
    personalData {
      ...FreelancerProfilePersonalDataFragment
    }
  }
}
Variables
{"profileKey": "abc123"}

Fields:

REST Field GraphQL Path Notes
ciphertext This is the profile_key Not available yet
dev_ac_agencies FreelancerProfile.agencies
dev_adj_score FreelancerProfile.aggregates.adjustedFeedbackScore
dev_adj_score_recent FreelancerProfile.aggregates.adjustedFeedbackScoreRecent
dev_billed_assignments FreelancerProfile.aggregates.billedAssignments
dev_city FreelancerProfile.personalData.location.city
dev_country FreelancerProfile.personalData.location.country
dev_eng_skill FreelancerProfile.languages
dev_groups FreelancerProfile.jobCategories.groups
dev_is_affiliated Not available yet
dev_last_activity FreelancerProfile.aggregates.lastActivity
dev_last_worked FreelancerProfile.aggregates.lastWorkedOn
dev_last_worked_ts FreelancerProfile.aggregates.lastWorkedOn
dev_portfolio_items_count FreelancerProfile.profileCompletenessSummary.portfolioCount
dev_portrait FreelancerProfile.personalData.portrait.portrait
dev_portrait_100 FreelancerProfile.personalData.portrait.portrait100
dev_portrait_32 FreelancerProfile.personalData.portrait.portrait32
dev_portrait_50 FreelancerProfile.personalData.portrait.portrait50
dev_profile_title FreelancerProfile.personalData.title
dev_recno_ciphertext Not available yet
dev_short_name Get the short name format. Name can be composed with FreelancerProfile.personalData.firstName & FreelancerProfile.personalData.lastName
dev_timezone FreelancerProfile.personalData.location.timezone
dev_tot_feedback FreelancerProfile.aggregates.totalFeedback
dev_total_hours FreelancerProfile.aggregates.totalHours
dev_ui_profile_access FreelancerProfile.userPreferences.visibilityLevel

Get freelancer profile by key

The API takes a profile key and returns detailed profile information about a freelancer or list of freelancers. This call returns an exhaustive list of attributes associated with the freelancer. If you're looking for a shorter summary, use the brief version of this call (GET /api/profiles/v1/providers/{profile_key}/brief.{format}).

REST
GET  /api/profiles/v1/providers/{profile_key}.{format} 
GraphQL
query getFreelancerProfile($profileKey: String!) {
  freelancerProfileByProfileKey(profileKey: $profileKey) {
    aggregates {
      ...FreelancerProfileAggregatesFragment
    }
    personalData {
      ...FreelancerProfilePersonalDataFragment
    }
  }
}
Variables
{"profileKey": "abc123"}

Fields:

REST Field GraphQL Path
ciphertext This is the profile_key
dev_ac_agencies FreelancerProfile.agencies
dev_adj_score FreelancerProfile.aggregates.adjustedFeedbackScore
dev_adj_score_recent FreelancerProfile.aggregates.adjustedFeedbackScoreRecent
dev_billed_assignments FreelancerProfile.aggregates.billedAssignments
dev_blurb FreelancerProfile.personalData.description
dev_city FreelancerProfile.personalData.location.city
dev_country FreelancerProfile.personalData.location.country
dev_eng_skill Get from FreelancerProfile.languages
dev_groups FreelancerProfile.jobCategories.groups
dev_last_activity FreelancerProfile.aggregates.lastActivity
dev_last_worked FreelancerProfile.aggregates.lastWorkedOn
dev_last_worked_ts FreelancerProfile.aggregates.lastWorkedOn
dev_portfolio_items_count FreelancerProfile.profileCompletenessSummary.portfolioCount
dev_portrait FreelancerProfile.personalData.portrait.portrait
dev_portrait_100 FreelancerProfile.personalData.portrait.portrait100
dev_portrait_32 FreelancerProfile.personalData.portrait.portrait32
dev_portrait_50 FreelancerProfile.personalData.portrait.portrait50
dev_profile_title FreelancerProfile.personalData.title
dev_recno_ciphertext FreelancerProfile.ciphertext
dev_short_name Get the short name format. Name can be composed with FreelancerProfile.personalData.firstName & FreelancerProfile.personalData.lastName
dev_timezone FreelancerProfile.personalData.location.timezone
dev_tot_feedback FreelancerProfile.aggregates.totalFeedback
dev_total_hours FreelancerProfile.aggregates.totalHours
dev_ui_profile_access FreelancerProfile.userPreferences.visibilityLevel
education FreelancerProfile.educationRecords
experiences FreelancerProfile.otherExperiences
job_categories FreelancerProfile.jobCategories
permalink FreelancerProfile.personalData.profileUrl
portfolio_items FreelancerProfile.projects
skills FreelancerProfile.skills
assignments FreelancerProfile.contracts

Companies and Teams

GraphQL OAuth2 scopes:

Name Description
Common Entities - Read-Only Access Grants read-only access to common entities like Organization, User, Freelancer Profile, etc.
Read Work diary company for public user Fetch workdiary snapshots information through for a input company

List companies

This call returns all the companies the currently authorized user has access to on Upwork. It is important to take into account that just because a user has access to a company does not mean he/she has access to all areas of a company. To find out exactly what permissions a user has within a specific company use 'Get roles' API call.

REST
GET  /api/hr/v2/companies.{format} 
GraphQL
query companies($userId: ID!) {
  companies(userId: $userId) {
    company {
      private {
        id
        companyName
        paymentVerification {
          status
        }
      }
    }
  }
}
Variables
{"userId": 4}

Fields:

REST Field GraphQL Path Description
reference companies.company.private.id Company reference
name companies.company.private.companyName Company name
payment_verification_status companies.company.private.paymentVerification.status Payment verified

Get company

Returns details regarding a specific company. If a user does not have access to this company, the call returns a 403 error. This API call does not return a list of teams within the company.

REST
GET  /api/hr/v2/companies/{company_reference}.{format} 
GraphQL
query getCompanyDetails($companyId: ID!) {
  company(id: $id) {
    private {
      id
      companyName
      paymentVerification {
        status
      }
    }
  }
}
Variables
{"id": "4"}

Fields:

REST Field GraphQL Path Description
reference query.company.private.id Company reference
name query.company.private.companyName Company name
payment_verification_status query.company.private.paymentVerification.status Payment verified

List teams

This call returns all the teams that a user has access to. Keep in mind that it returns teams across different companies.

REST
GET  /api/hr/v2/teams.{format} 
GraphQL
{
  organization {
    childOrganization {
      id
      company {
        name
      }
      parentOrganization {
        id
        company {
          name
        }
      }
    }
  }
}

Fields:

REST Field GraphQL Path Description
id query/organization/childOrganization/id Team ID
name query/organization/childOrganization/company/name Company name
parent_team__id query/organization/childOrganization/parentOrganization/id Parent team ID
company_name query/organization/childOrganization/parentOrganization/company/name Parent company name

List users in team

This call returns a list of teams within the company being referenced (as long as the user has access to the referenced company).

REST
GET  /api/hr/v2/teams/{team_reference}/users.{format} 
GraphQL
query getChildOrganizationStaff($childOrganizationId: ID!) {
  organization {
    childOrganization(id: $childOrganizationId) {
      staffs {
        edges {
          node {
            user {
              id
              name
              publicUrl
            }
            staffType
            activationStatus
          }
        }
      }
    }
  }
}
Variables
{"childOrganizationId": "yourChildOrganizationIdHere"}

Fields:

REST Field GraphQL Path Description
Id query/organization/childOrganization/staffs/edges/node/user/id User ID
reference query/organization/childOrganization/staffs/edges/node/id User reference
public_url query/organization/childOrganization/staffs/edges/node/user/publicUrl User's public profile url
is_provider query/organization/childOrganization/staffs/edges/node/organization/legacyType Is it a contractor
status query/organization/childOrganization/staffs/edges/node/staffType User status in this team

Get Work Diary

The Work Diary method retrieves all snapshots from a single user account within a single day. Keep in mind that a day is dependent on server time and not the day in which the query is made. Make sure to test with various locations before you're done. If task ID is empty, the endpoint will group the data by contract and memo, otherwise by task ID.

REST
GET  /api/team/v3/workdiaries/companies/{company_id}/{date}.{format} 
GraphQL
query getWorkDiaryCompany($companyId: ID!, $date: String!) {
  workDiaryCompany(workDiaryCompanyInput: { companyId: $companyId, date: $date }) {
    total
    snapshots {
      contract {
        id
        contractTitle
        userId
      }
      user {
        id
        name
        portraitUrl
      }
      duration
      durationInt
      task {
        id
        code
        description
        memo
      }
      time {
        trackedTime
        manualTime
        overtime
        firstWorked
        lastWorked
        firstWorkedInt
        lastWorkedInt
        lastScreenshot
      }
      screenshots {
        activity
        screenshotUrl
        screenshotImage
        screenshotImageLarge
        screenshotImageMedium
        screenshotImageThumbnail
        hasWebcam
        hasScreenshot
        webcamUrl
        webcamImage
        webcamImageThumbnail
        flags {
          hideScreenshot
          downSampleScreenshots
        }
      }
    }
  }
}
Variables
{"companyId": 4, "date": "abc123"}

Fields:

REST Field GraphQL Path Description
total total Total number of records
contracts.user_id snapshots.contract.userId User ID
contracts.contract_title snapshots.contract.contractTitle Contract title
users.name snapshots.user.name User name
users.portrait_url snapshots.user.portraitUrl Portrait URL
snapshots.task.id Snapshots.task.id ID
snapshots.task.code Snapshots.task.code Code
snapshots.task.description Snapshots.task.description Description
snapshots.task.memo Snapshots.task.memo Memo
snapshots.contract_id snapshots.contract.id Contract ID
snapshots.duration snapshots.duration Duration
snapshots.duration_int snapshots.durationInt Durarion (in minutes)
snapshots.user_id snapshots.userId User ID
snapshots.time.tracked_time snapshots.time.trackedTime Tracked time
snapshots.time.manual_time snapshots.time.manualTime Manual time
snapshots.time.overtime snapshots.time.overtime Overtime
snapshots.time.first_worked snapshots.time.firstWorked First worked time
snapshots.time.last_worked snapshots.time.lastWorked Last worked time
snapshots.time.first_worked_int snapshots.time.firstWorkedInt First worked timestamp
snapshots.time.last_worked_int snapshots.time.lastWorkedInt Last worked timestamp
snapshots.time.last_screenshot snapshots.time.lastScreenshot Last screenshot
snapshots.screenshots snapshots.screenshots List of screenshots
snapshots.snapshot_api snapshots.screenshots[*].screenshotUrl Link to snapshot API
snapshots.last_worked_snapshot_api deprecated Link to snapshots API with the last worked snapshot

Get Work Diary by Contract

The Work Diary method retrieves all snapshots from a single user account within a single day.

REST
GET  /api/team/v3/workdiaries/contracts/{contract_id}/{date}.{format} 
GraphQL
{
  workDiaryContract(
    workDiaryContractInput: {
      contractId: $contractId,
      date: $date,
      offsetInSeconds: offsetInSeconds,
      useLegacy: useLegacy
    }
  ) {
    workDiaryMetadata {
      user {
        id
        name
      }
      timezoneOffset
      archivingDateTime
    }
    workDiaryTimeCells {
      cellDateTime {
        rawValue
        displayValue
      }
      overtime
      activityLevel
      memo
    }
  }
}
Variables
{"contractId": "4", "date": "abc123", "offsetInSeconds": 987, "useLegacy": true}

Fields:

REST Field GraphQL Path Description
snapshots.assignment.id workDiaryContract/id Contract ID
snapshots.user.uid workDiaryContract/workDiaryMetadata/user/id User ID
snapshots.user.first_name workDiaryContract/workDiaryMetadata/user/lastName Last name
snapshots.user.portrait_url workDiaryContract/workDiaryMetadata/user/photoUrl Portrait URL
snapshots.user.timezone_offset workDiaryContract/workDiaryMetadata/timezoneOffset Timezone offset
snapshots.user.archiving_time workDiaryContract/workDiaryMetadata/archivingDateTime Archiving time
snapshots.snapshots.cell_time workDiaryContract/workDiaryTimeCells/cellDateTime Cell timestamp
snapshots.snapshots.time workDiaryContract/workDiaryTimeCells/snapshotDateTime Snapshot timestamp
snapshots.snapshots.activity workDiaryContract/workDiaryTimeCells/activityLevel Flag indicates the level of activity
snapshots.snapshots.memo workDiaryContract/workDiaryTimeCells/memo Memo
snapshots.snapshots.task.id workDiaryContract/workDiaryTimeCells/task/id ID
snapshots.snapshots.task.description workDiaryContract/workDiaryTimeCells/task/description Description
snapshots.snapshots.mouse_events_count workDiaryContract/workDiaryTimeCells/mouseEventsCount Mouse events
snapshots.snapshots.keyboard_events_count workDiaryContract/workDiaryTimeCells/keyboardEventsCount Keyboard events
snapshots.snapshots.active_window_title workDiaryContract/workDiaryTimeCells/activeWindowTitle Active window title
snapshots.snapshots.flags.hide_screenshots workDiaryContract/workDiaryTimeCells/hideScreenshots Flag indicates hidden screenshot
snapshots.snapshots.has_screenshot workDiaryContract/workDiaryTimeCells/hasScreenshot Flag indicates if the cell has a screenshot
snapshots.snapshots.screenshot_url workDiaryContract/workDiaryTimeCells/screenshotImageUrl Screenshot URL
snapshots.snapshots.screenshot_img_med workDiaryContract/workDiaryTimeCells/screenshotImageUrlMedium Medium screenshot image
snapshots.snapshots.screenshot_img_thmb workDiaryContract/workDiaryTimeCells/screenshotImageThumbnail Screenshot thumbnail
snapshots.snapshots.has_webcam workDiaryContract/workDiaryTimeCells/webcamEnabled Flag indicates if webcam image exists
snapshots.snapshots.webcam_url workDiaryContract/workDiaryTimeCells/webcamImageUrl Webcam URL
snapshots.snapshots.webcam_img_thmb workDiaryContract/workDiaryTimeCells/webcamImageThumbnail Webcam thumbnail

Milestone Submissions

GraphQL OAuth2 scopes:

Name Description
Offer - Read And Write Access Grants read/write access to offers

Submit work to a milestone

This API call allows a freelancer to submit work to a milestone to be approved by the client. Note that the user must be authorized in Upwork and must be a freelancer of a contract or AM of such freelancer.

REST
POST  /api/hr/v3/fp/submissions.{format} 
GraphQL
mutation freelancerSubmitMilestone($milestoneId: String, $noteToClient: String, $amount: String) {
  submitMilestoneByFreelancer(
    input: { id: $id, noteToClient: $noteToClient, amount: $amount }
  ) {
    id
  }
}
Variables
{"id": 4, "noteToClient": "abc123", "amount": "abc123"}

Fields:

REST Field GraphQL Path Description
milestone_id FreelancerSubmitMilestoneInput.id Milestone reference
noteToClient FreelancerSubmitMilestoneInput.noteToClient Notes from freelancer to client about work that was done
amount FreelancerSubmitMilestoneInput.amount Amount requested by the freelancer

Approve a milestone submission

This API call allows a Hiring Manager to approve the submission of work to a milestone made by the freelancer. Note that the user must be authorized in Upwork and must be a Hiring Manager in the team to be able to approve a milestone submission

REST
PUT  /api/hr/v3/fp/submissions/{submission_id}/approve.{format} 
GraphQL
mutation approveSubmitMilestone($milestoneId: String, $paidAmount: String, $bonusAmount: String, $paymentComment: String, $underpaymentReason: String, $noteToContractor: String) {
  approveMilestone(
    input: {
      id: $milestoneId,
      paidAmount: $paidAmount,
      bonusAmount: $bonusAmount,
      paymentComment: $paymentComment,
      underpaymentReason: $underpaymentReason,
      noteToContractor: $noteToContractor
    }
  ) {
    id
  }
}
Variables
{
  "milestoneId": "4",
  "paidAmount": "xyz789",
  "bonusAmount": "abc123",
  "paymentComment": "abc123",
  "underpaymentReason": "xyz789",
  "noteToContractor": "abc123"
}

Fields:

REST Field GraphQL Path Description
submission_id ApproveMilestoneInput.id Submission reference
amount ApproveMilestoneInput.paidAmount Amount of money to be paid
bonus ApproveMilestoneInput.bonusAmount Amount of money paid as bonus
pay_comments ApproveMilestoneInput.paymentComment Comments on payment
underpayment_reason ApproveMilestoneInput.underpaymentReason Reason for a smaller payment than the one agreed. Values description: `329` - Payment lower due to freelancer performance; `330` - Freelancer is performing well, but the scope of work changed; `331` - Freelancer is performing well, but I decided to make an earlier payment; `332` - Payment is lower for other reasons, but freelancer is performing well. Valid values: 329, 330, 331, 332
note2contractor ApproveMilestoneInput.noteToContractor Notes from the client to the freelancer

Reject a milestone submission

This API call allows a Hiring Manager to reject the submission of work to a milestone. Note that the user must be authorized in Upwork and must be a Hiring Manager in the team to be able to reject the submission.

REST
PUT  /api/hr/v3/fp/submissions/{submission_id}/reject.{format} 
GraphQL
mutation rejectSubmittedMilestone($milestoneId: String, $noteToContractor: String) {
  rejectSubmittedMilestone(
    input: { id: $milestoneId, noteToContractor: $noteToContractor }
  ) {
    id
  }
}
Variables
{"milestoneId": "4", "noteToContractor": "abc123"}

Fields:

REST Field GraphQL Path Description
submission_id RejectMilestoneSubmissionInput.id Submission reference
note2contractor RejectMilestoneSubmissionInput.noteToContractor Notes from the client to the freelancer

Milestones Create/Update

GraphQL OAuth2 scopes:

Name Description
Offer - Read-Only Access Grants read-only access to offer's information
Offer - Read And Write Access Grants read/write access to offers

Create a milestone

This API call allows a Hiring Manager to create a milestone. Note that the user must be authorized in Upwork and must be Hiring Manager in the team to be able to create a milestone

REST
POST  /api/hr/v3/fp/milestones.{format} 
GraphQL
mutation createMilestone(
  $offerId: ID!,
  $contractId: ID!,
  $description: String!,
  $instruction: String!,
  $depositAmount: String!,
  $dueDate: String!,
  $attachmentIds: [ID!]
) {
  createMilestone(
    input: {
      offerId: $offerId,
      contractId: $contractId,
      description: $description,
      instruction: $instruction,
      depositAmount: $depositAmount,
      dueDate: $dueDate,
      attachmentIds: $attachmentIds
    }
  ) {
    id
    createdBy {
      id
      nid
      rid
    }
    modifiedBy {
      id
      nid
      rid
    }
    dueDateTime
    state
    description
    currentEscrowAmount {
      rawValue
      displayValue
      currency
    }
    depositAmount {
      rawValue
      displayValue
      currency
    }
    fundedAmount {
      rawValue
      displayValue
      currency
    }
    paid {
      rawValue
      displayValue
      currency
    }
    overpayment {
      rawValue
      displayValue
      currency
    }
    bonus {
      rawValue
      displayValue
      currency
    }
    previousMilestoneUnusedDeposit {
      rawValue
      displayValue
      currency
    }
    submissionCount
    sequenceId
    payComments
    lastSubmissionCreatedTime
    createdDateTime
    modifiedDateTime
    instructions
    submissionEvents {
      submission {
        id
        createdDateTime
        modifiedDateTime
        amount {
          rawValue
          displayValue
          currency
        }
        sequenceId
      }
      submissionMessage {
        createdDateTime
        message
      }
      revisionMessage {
        createdDateTime
        message
      }
    }
  }
}
Variables
{
  "offerId": 4,
  "contractId": 4,
  "description": "abc123",
  "instruction": "abc123",
  "depositAmount": "xyz789",
  "dueDate": "xyz789",
  "attachmentIds": ["4"]
}

Fields:

REST Field GraphQL Path
contract_reference CreateMilestoneInput.contractId
milestone_description CreateMilestoneInput.description
deposit_amount CreateMilestoneInput.depositAmount
due_date CreateMilestoneInput.dueDate
This resource returns the ID of the milestone created createMilestone.id

Edit a milestone

This API call allows a Hiring Manager to edit a milestone. Note that the user must be authorized in Upwork and must be a Hiring Manager in the team to be able to edit the milestone

REST
PUT  /api/hr/v3/fp/milestones/{milestone_id}.{format} 
GraphQL
mutation editMilestone(
  $id: ID!,
  $description: String,
  $instructions: String,
  $depositAmount: String,
  $dueDate: String,
  $attachments: [ID!],
  $message: String,
  $sequenceId: Int
) {
  editMilestone(
    input: {
      id: $id,
      description: $description,
      instructions: $instructions,
      depositAmount: $depositAmount,
      dueDate: $dueDate,
      attachments: $attachments,
      message: $message,
      sequenceId: $sequenceId
    }
  ) {
    id
    createdBy {
      id
      nid
      rid
    }
    modifiedBy {
      id
      nid
      rid
    }
    dueDateTime
    state
    description
    currentEscrowAmount {
      rawValue
      displayValue
      currency
    }
    depositAmount {
      rawValue
      displayValue
      currency
    }
    fundedAmount {
      rawValue
      displayValue
      currency
    }
    paid {
      rawValue
      displayValue
      currency
    }
    overpayment {
      rawValue
      displayValue
      currency
    }
    bonus {
      rawValue
      displayValue
      currency
    }
    previousMilestoneUnusedDeposit {
      rawValue
      displayValue
      currency
    }
    submissionCount
    sequenceId
    payComments
    lastSubmissionCreatedTime
    createdDateTime
    modifiedDateTime
    instructions
    submissionEvents {
      submission {
        id
        createdDateTime
        modifiedDateTime
      }
    }
  }
}
Variables
{
  "id": 4,
  "description": "xyz789",
  "instructions": "abc123",
  "depositAmount": "xyz789",
  "dueDate": "xyz789",
  "attachments": ["4"],
  "message": "abc123",
  "sequenceId": 987
}

Fields:

REST Field GraphQL Path
milestone_id EditMilestoneInput.id
milestone_description EditMilestoneInput.description
deposit_amount EditMilestoneInput.depositAmount
message EditMilestoneInput.message
due_date EditMilestoneInput.dueDate
Returns 200 OK in case of success Returns updated Milestone Object

Activate a milestone

This API call allows a Hiring Manager to activate a Milestone. Note that the user must be authorized in Upwork and must be a Hiring Manager in the team to be able to activate the milestone

REST
PUT  /api/hr/v3/fp/milestones/{milestone_id}/activate.{format} 
GraphQL
mutation activateMilestone(
  $id: ID!,
  $message: String
) {
  activateMilestone(
    input: {
      id: $id,
      message: $message
    }
  ) {
    id
    createdBy {
      id
      nid
      rid
    }
    modifiedBy {
      id
      nid
      rid
    }
    dueDateTime
    state
    description
    currentEscrowAmount {
      rawValue
      displayValue
      currency
    }
    depositAmount {
      rawValue
      displayValue
      currency
    }
    fundedAmount {
      rawValue
      displayValue
      currency
    }
    paid {
      rawValue
      displayValue
      currency
    }
    overpayment {
      rawValue
      displayValue
      currency
    }
    bonus {
      rawValue
      displayValue
      currency
    }
    previousMilestoneUnusedDeposit {
      rawValue
      displayValue
      currency
    }
    submissionCount
    sequenceId
    payComments
    lastSubmissionCreatedTime
    createdDateTime
    modifiedDateTime
    instructions
    submissionEvents {
      submission {
        id
        createdDateTime
        modifiedDateTime
        amount {
          rawValue
          displayValue
          currency
        }
        sequenceId
      }
      submissionMessage {
        createdDateTime
        message
      }
      revisionMessage {
        createdDateTime
        message
      }
    }
  }
}
Variables
{"id": "4", "message": "xyz789"}

Fields:

REST Field GraphQL Path
milestone_id ActivateMilestoneInput.id
message ActivateMilestoneInput.message
Returns 200 OK in case of success Returns activated Milestone Object

Approve a milestone

Closes the milestone by paying the deposit amount if no amount is specified

REST
PUT  /api/hr/v3/fp/milestones/{milestone_id}/approve.{format} 
GraphQL
mutation approveMilestone(
  $id: ID!,
  $paidAmount: String,
  $bonus: String,
  $paymentComment: String,
  $underpaymentReason: String,
  $noteToContractor: String
) {
  approveMilestone(
    input: {
      id: $id,
      paidAmount: $paidAmount,
      bonusAmount: $bonus,
      paymentComment: $paymentComment,
      underpaymentReason: $underpaymentReason,
      noteToContractor: $noteToContractor
    }
  ) {
    id
    createdBy {
      id
      nid
      rid
    }
    modifiedBy {
      id
      nid
      rid
    }
    dueDateTime
    state
    description
    currentEscrowAmount {
      rawValue
      displayValue
      currency
    }
    depositAmount {
      rawValue
      displayValue
      currency
    }
    fundedAmount {
      rawValue
      displayValue
      currency
    }
    paid {
      rawValue
      displayValue
      currency
    }
    overpayment {
      rawValue
      displayValue
      currency
    }
    bonus {
      rawValue
      displayValue
      currency
    }
    previousMilestoneUnusedDeposit {
      rawValue
      displayValue
      currency
    }
    submissionCount
    sequenceId
    payComments
    lastSubmissionCreatedTime
    createdDateTime
    modifiedDateTime
    instructions
    submissionEvents {
      submission {
        id
        createdDateTime
        modifiedDateTime
        amount {
          rawValue
          displayValue
          currency
        }
        sequenceId
      }
      submissionMessage {
        createdDateTime
        message
      }
      revisionMessage {
        createdDateTime
        message
      }
    }
  }
}
Variables
{
  "id": "4",
  "paidAmount": "xyz789",
  "bonusAmount": "abc123",
  "paymentComment": "abc123",
  "underpaymentReason": "xyz789",
  "noteToContractor": "abc123"
}

Fields:

REST Field GraphQL Path
milestone_id ApproveMilestoneInput.id
amount ApproveMilestoneInput.paidAmount
bonus ApproveMilestoneInput.bonusAmount
pay_comments ApproveMilestoneInput.paymentComment
underpayment_reason ApproveMilestoneInput.underpaymentReason
note2contractor ApproveMilestoneInput.noteToContractor
Returns 200 OK in case of success Returns approved Milestone Object

Delete a milestone

This API call allows a Hiring Manager to delete a milestone. Note that the user must be authorized in Upwork and must be a Hiring Manager in the team to be able to delete the milestone. Only milestones with status `not_funded` can be deleted

REST
DELETE  /api/hr/v3/fp/milestones/{milestone_id}.{format} 
GraphQL
mutation deleteMilestone($id: ID!) {
  deleteMilestone(input: {id: $id})
}
Variables
{"id": "4"}

Fields:

REST Field GraphQL Path
milestone_id DeleteMilestoneInput.id
Returns 200 OK in case of success Returns Boolean of true in case of success

Activities

GraphQL OAuth2 scopes:

Name Description
Activity Entities - Read-Only Access Grants read-only access to activity entities
Activity Entities - Read and Write Access Grants read and write access to activity entities

List team activities

Returns details regarding a specific company. If a user does not have access to this company, the call returns a 403 error. This API call does not return a list of teams within the company.

REST
GET  /api/otask/v1/tasks/companies/{company_id}/teams/{team_id}/tasks.{format} 
GraphQL
query teamActivities(
  $orgId: ID!,
  $teamId: ID,
  $page: PageFilterInput,
) {
  teamActivities(
    orgId: $orgId,
    teamId: $teamId,
    page: $page,
  ) {
    totalCount
    edges {
       node {
        url
        userId
        code
        companyId
        recordId
        description
      }
    }
    page {
      pageOffset
      pageSize
    }
  }
}
Variables
{"orgId": "4", "teamId": 4, "page": {"pageOffset": 123, "pageSize": 987}}

Fields:

REST Field GraphQL Path Description
record_id Activity.recordId 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 Activity.companyId This is the ID of the company.
user_id Activity.userId The Upwork ID of the user.
code Activity.code This is specified by the user. It could be used to reference a bug ID on a third-party system.
description Activity.description The text description contained within the activity.
URL 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.

List activities for specific engagement

Authorized user must have hiring permissions in order to use this API call.

REST
GET  /api/tasks/v2/tasks/contracts/{engagement_ref}.{format} 
GraphQL
query teamActivities(
  $orgId: ID!,
  $filter: ActivityFilterInput
  $page: PageFilterInput,
) {
  teamActivities(
    orgId: $orgId,
    filter: $filter
    page: $page,
  ) {
    totalCount
    edges {
       node {
        url
        userId
        code
        companyId
        recordId
        description
      }
    }
    page {
      pageOffset
      pageSize
    }
  }
}
Variables
{
  "orgId": "4",
  "page": {"pageOffset": 123, "pageSize": 987},
  "filter": {"contractId": 4}
}

Fields:

REST Field GraphQL Path Description
record_id Activity.recordId 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 Activity.companyId This is the ID of the company.
user_id Activity.userId The Upwork ID of the user.
code Activity.code This is specified by the user. It could be used to reference a bug ID on a third-party system.
description Activity.description The text description contained within the activity.
URL 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.

Get team activity by code

This call returns details on a single activity or a set of activities within a team.

REST
GET  /api/otask/v1/tasks/companies/{company_id}/teams/{team_id}/tasks/{code}.{format} 
GraphQL
query teamActivities(
  $orgId: ID!,
  $teamId: ID,
  $filter: ActivityFilterInput,
  $page: PageFilterInput,
) {
  teamActivities(
    orgId: orgId
    teamId: teamId
    page: $page
    filter: $filter
  ) {
    totalCount
    edges {
      node {
        url
        userId
        code
        companyId
        recordId
        description
      }
    }
    page {
      pageOffset
      pageSize
    }
  }
}
Variables
{
  "orgId": "4",
  "teamId": 4,
  "page": {"pageOffset": 123, "pageSize": 987},
  "filter": {"codes": ["xyz789"]}
}

Fields:

REST Field GraphQL Path Description
record_id Activity.recordId 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 Activity.companyId This is the ID of the company.
user_id Activity.userId The Upwork ID of the user.
code Activity.code This is specified by the user. It could be used to reference a bug ID on a third-party system.
description Activity.description The text description contained within the activity.
URL 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.

Create activity at team level

A user needs to have hiring manager privileges within the team in order to create an activity at team level.

REST
POST  /api/otask/v1/tasks/companies/{company_id}/teams/{team_id}/tasks.{format} 
GraphQL
mutation addTeamActivity(
  $orgId: ID!,
  $teamId: ID!,
  $request: TeamActivityInput!
) {
  addTeamActivity(
    orgId: $orgId
    teamId: $teamId
    request: $request
  ) {
    id
    success
  }
}
Variables
{
  "orgId": "4",
  "teamId": 4,
  "request": {
    "code": "abc123",
    "description": "abc123",
    "url": "xyz789",
    "contractIds": [4],
    "allInCompany": true
  }
}

Fields:

REST Field GraphQL Path Description
code AddTeamActivityRequest.code This is specified by the user. It could be used to reference a bug ID on a third-party system.
description AddTeamActivityRequest.description The text description contained within the activity.
URL AddTeamActivityRequest.url This is specified by the user. It can be used to link to a third-party bug tracking system or any related URL.
engagements AddTeamActivityRequest.contractIds[] A list of engagements that are to be assigned to the created activity. It can be a single engagement ID, or a semicolon (';') separated list of IDs.
all_in_company AddTeamActivityRequest.allInCompany If set to `1`, then the created activity is assigned to all engagements that exist in the company at the moment. Valid values: 0, 1

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.

REST
PUT  /api/otask/v1/tasks/companies/{company_id}/teams/{team_id}/tasks/{code}.{format} 
GraphQL
mutation updateTeamActivity(
  $orgId: ID!,
  $teamId: ID!,
  $request: UpdateTeamActivityRequest!
) {
  updateTeamActivity(
    orgId: $orgId
    teamId: $teamId
    request: $request
) {
    success
  }
}
Variables
{
  "orgId": "4",
  "teamId": 4,
  "request": {
    "code": "abc123",
    "description": "abc123",
    "url": "xyz789",
    "contractIds": [4],
    "allInCompany": true
  }
}

Fields:

REST Field GraphQL Path Description
code UpdateTeamActivityRequest.code This is specified by the user. It could be used to reference a bug ID on a third-party system.
description UpdateTeamActivityRequest.description The text description contained within the activity.
URL UpdateTeamActivityRequest.url This is specified by the user. It can be used to link to a third-party bug tracking system or any related URL.
engagements UpdateTeamActivityRequest.contractIds[] A list of engagements that are to be assigned to the created activity. It can be a single engagement
all_in_company UpdateTeamActivityRequest.allInCompany Created activity is assigned to all engagements that exist in the company at the moment.

Assign engagements to the list of activities

Activity appears in freelancer's team client only if his engagement is assigned to the activity and activities are activated for the ongoing contract. This call overrides assigned engagements for the given activities. For example, if you pass empty `task_codes` or just omit this parameter, freelancer's engagement is unassigned from all the activities it is assigned to.

REST
PUT  /api/otask/v1/tasks/companies/{company_id}/teams/{team_id}/engagements/{engagement}/tasks.{format} 
GraphQL
mutation assignTeamActivityToTheContract(
  $orgId: ID!,
  $teamId: ID!,
  $contractId: ID!,
  $codes: [String!]!
) {
  assignTeamActivityToTheContract(
    orgId: $orgId
    teamId: $teamId
    contractId: $contractId
    codes: $codes
  ) {
    success
  }
}
Variables
{"orgId": "4", "teamId": 4, "contractId": 4, "codes": ["abc123"]}

Fields:

REST Field GraphQL Path Description
company_id orgId The company ID. Use the `parent_team__id` value from the 'Get teams' API call.
team_id teamId The team ID
engagement contractId Engagement ID that is assigned/unassigned to the given list of activities

Archive activities

If you want to archive activity for company, use the `company_id` value for `team_id` as well.

REST
PUT  /api/otask/v1/tasks/companies/{company_id}/teams/{team_id}/archive/{code}.{format} 
GraphQL
mutation archiveTeamActivity(
  $orgId: ID!,
  $teamId: ID!,
  $codes: [String!]!
) {
  archiveTeamActivity(
    orgId: $orgId
    teamId: $teamId
    codes: $codes
  ) {
    success
  }
}
Variables
{"orgId": "4", "teamId": 4, "codes": ["abc123"]}

Fields:

REST Field GraphQL Path Description
company_id orgId The company ID. Use the `parent_team__id` value from the 'Get teams' API call.
team_id teamId The team ID
code codes[] Activity tracking code

Unarchive activities

If you want to unarchive activity for company, use the `company_id` value for `team_id` as well.

REST
PUT  /api/otask/v1/tasks/companies/{company_id}/teams/{team_id}/unarchive/{code}.{format} 
GraphQL
mutation unarchiveTeamActivity(
  $orgId: ID!,
  $teamId: ID!,
  $codes: [String!]!
) {
  unarchiveTeamActivity(
    orgId: $orgId
    teamId: $teamId
    codes: $codes
  ) {
    success
  }
}
Variables
{"orgId": "4", "teamId": 4, "codes": ["abc123"]}

Fields:

REST Field GraphQL Path Description
company_id orgId The company ID. Use the `parent_team__id` value from the 'Get teams' API call.
team_id teamId The team ID
code codes[] Activity tracking code

Metadata

GraphQL OAuth2 scopes:

Name Description
Ontology - Read-Only Access Grants read-only access to ontology information
Common Entities - Read-Only Access Grants read-only access to common entities like Organization, User, Freelancer Profile, etc.

List specialties

This call returns a list of specialties available for a specific topic, which you can get using List Categories query.

REST
GET  /api/profiles/v1/metadata/specialties.{format} 
GraphQL
{
  query ontologyCategories {
    ontologyCategories {
      id
      preferredLabel
      altLabel
      slug
      ontologyId
      subcategories {
        ...OntologySubcategoryFragment
      }
      services {
        ...OntologyServiceFragment
      }
    }
  }
}

Fields:

REST Field GraphQL Path Description
title query/ontologyCategories/subcategories/preferredLabel Title
id query/ontologyCategories/subcategories/id ID

List categories

This call returns a list of categories for a job/freelancer profile from new structure.

REST
GET  /api/profiles/v2/metadata/categories.{format} 
GraphQL
{
  query ontologyCategories {
    ontologyCategories {
      id
      preferredLabel
      altLabel
      slug
      ontologyId
      subcategories {
        ...OntologySubcategoryFragment
      }
      services {
        ...OntologyServiceFragment
      }
    }
  }
}

Fields:

REST Field GraphQL Path Description
title query/ontologyCategories/preferredLabel Title
id query/ontologyCategories/id ID
topics.title query/ontologyCategories/subcategories/preferredLabel Topic title
topics.id query/ontologyCategories/subcategories/id Topic ID

List skills

This call returns a list of skills available in a freelancer's profile.

REST
GET  /api/profiles/v2/metadata/skills.{format} 
GraphQL
{
  query ontologyBrowserSkills(
    $limit: Int!,
    $offset: Int
  ) {
    ontologyBrowserSkills(
      limit: $limit,
      offset: $offset
    ) {
      id
      preferredLabel
    }
  }
}
Variables
{"limit": 10, "offset": 20}

Fields:

REST Field GraphQL Path Description
no specific field, a part of array query/ontologyBrowserSkills/preferredLabel Skill

List regions

This call returns a list of county regions.

REST
GET  /api/profiles/v1/metadata/regions.{format} 
GraphQL
{
  query regions {
    regions {
      id
      name
      parentRegion {
        ...RegionFragment
      }
    }
  }
}

Fields:

REST Field GraphQL Path Description
alias Not available, use query/regions/id instead Alias
title query/regions/name Title

List reasons

This call returns a list of reasons by specified type.

REST
GET  /api/profiles/v1/metadata/reasons.{format} 
GraphQL
{
  query reasons(
    $reasonType: ReasonType!,
    $all: Boolean
  ) {
    reasons(
      reasonType: $reasonType,
      all: $all
    ) {
      id
      reason
      alias
    }
  }
}
Variables
{"reasonType": "JOB_POSTING_CLOSE", "all": true}

Fields:

REST Field GraphQL Path Description
first element of array query/reasons/id Reference
second element of array query/reasons/reason Name
third element of array query/reasons/alias Alias

Users

GraphQL OAuth2 scopes:

Name Description
View UserDetails - Read only Scope for user to fetch user details

Referenced User

This API call returns details about the referenced user.

REST
GET  /api/hr/v2/users/{user_reference}
GET /api/hr/v2/users/{user_reference}.{format}
GraphQL
query userDetails($id: ID!) {
  userDetails(id: $id) {
    id
    nid
    rid
    name
    firstName
    lastName
    photoUrl
    publicUrl
    email
    location {
      timezone
      offsetToUTC
    }
    ciphertext
  }
}
Variables
{"id": 4}

Fields:

REST Field GraphQL Path Description
reference rid The reference ID of the user
id id The literal ID of the user
first_name firstName The user’s first name
last_name lastName The user’s last name
timezone location.timezone The user’s time zone
timezone_offset location.offsetToUTC The time zone offset in seconds
is_provider Deprecated Indicates whether the user is a freelancer (can be hired) or not
email email User’s email
public_url publicUrl The URL to the public profile

Jobs

GraphQL OAuth2 scopes:

Name Description
Read marketplace Job Postings Scope to read marketplace Job Postings for enterprise user

Search for jobs

The search parameters mirror the options available on the site plus options to configure the format of your results

REST
GET  /api/profiles/v2/search/jobs.{format} 
GraphQL
query marketplaceJobPostings(
  $marketPlaceJobFilter: MarketplaceJobFilter,
  $searchType: MarketplaceJobPostingSearchType,
  $sortAttributes: [MarketplaceJobPostingSearchSortAttribute]
) {
  marketplaceJobPostings(
    marketPlaceJobFilter: $marketPlaceJobFilter,
    searchType: $searchType,
    sortAttributes: $sortAttributes
  ) {
    totalCount
    edges {
      ...MarketplaceJobpostingSearchEdgeFragment
    }
    pageInfo {
      ...PageInfoFragment
    }
  }
}
Variables
{
  "searchExpression_eq": "abc123",
  "skillExpression_eq": "xyz789",
  "titleExpression_eq": "abc123",
  "searchTerm_eq": {
    "andTerms_all": ["xyz789"],
    "orTerms_any": ["abc123"],
    "exactTerms_any": ["xyz789"],
    "excludeTerms_any": ["abc123"]
  },
  "categoryIds_any": ["4"],
  "subcategoryIds_any": ["4"],
  "occupationIds_any": [4],
  "ontologySkillIds_all": [4],
  "sinceId_eq": "abc123",
  "maxId_eq": "abc123",
  "jobType_eq": "HOURLY",
  "duration_eq": "WEEK",
  "workload_eq": "FULL_TIME",
  "clientHiresRange_eq": {"rangeStart": 987, "rangeEnd": 987},
  "clientFeedBackRange_eq": {"rangeStart": 987.65, "rangeEnd": 123.45},
  "budgetRange_eq": {"rangeStart": 987, "rangeEnd": 987},
  "verifiedPaymentOnly_eq": false,
  "previousClients_eq": true,
  "experienceLevel_eq": "ENTRY_LEVEL",
  "locations_any": ["abc123"],
  "cityId_any": ["xyz789"],
  "zipCodeId_any": ["xyz789"],
  "radius_eq": 987,
  "areaId_any": ["xyz789"],
  "timezone_eq": "xyz789",
  "usState_eq": "abc123",
  "daysPosted_eq": 987,
  "jobPostingAccess": "PUBLIC_INDEX",
  "ptcIds_any": [4],
  "ptcOnly_eq": true,
  "enterpriseOnly_eq": true,
  "proposalRange_eq": {"rangeStart": 987, "rangeEnd": 987},
  "pagination_eq": {"after": "abc123", "first": 987},
  "area_eq": {"latitude": 987.65, "longitude": 123.45, "radius": 123.45},
  "preserveFacet_eq": "abc123",
  "userLocationMatch_eq": true,
  "visitorCountry_eq": "abc123"
}

Fields:

REST Field GraphQL Path Description
q marketPlaceJobFilter.searchExpression_eq The search query. At least one of the `q`, `title`, `skill` parameters should be specified.
title marketPlaceJobFilter.titleExpression_eq Searches for the title in the freelancer's profile. At least one of the `q`, `title`, `skill` parameters should be specified.
skills marketPlaceJobFilter.skillExpression_eq Searches for skills of freelancer's profile. At least one of the `q`, `title`, `skill` parameters should be specified.
category2 marketPlaceJobFilter.categoryIds_any The category (V2) of the freelancer's profile. Use Metadata resource to get it. You can get it via Metadata Category (v2) resource.
subcategory2 marketPlaceJobFilter.subcategoryIds_any The subcategory of the job according to the list of Categories 2.0. Example: `Web & Mobile Development`. You can get it via Metadata Category (v2) resource.
duration marketPlaceJobFilter.duration_eq The duration of the job. Valid values: week, month, semester, ongoing
workload marketPlaceJobFilter.workload_eq Indicates the workload for the job. Valid values: as_needed, part_time, full_time
client_feedback marketPlaceJobFilter.clientFeedBackRange_eq A number or range used to filter the search by jobs posted by clients with a rating equal to, more or less than, or within the values provided. If the value is `None`, then jobs from clients without rating are returned. Single parameters such as `1` or `2,3` are valid (comma separated values result in `OR` queries). Ranges such as `[2 TO 4]` are also valid. Examples: `5.0` - the rating is equal to 5.0; `1-5` - the rating is so that 1 <= n <= 5; `1-` - the rating is >=1; `-5` - the rating is <= 5.
client_hires marketPlaceJobFilter.clientHiresRange_eq A number or range used to filter the search by clients with a number of past hires equal to, more or less than, or within the values provided. Single parameters such as `1` or `2,3` are valid (comma-separated values result in `OR` queries). Ranges such as `[10 TO 20]` are also valid. Examples: `5` - the number of past hires is to 5; `0-10`: number of past hires is 0 <= n <= 10; `10-` - the number of past hires is >=10; `-5` - the number of past hires is <= 5.
budget marketPlaceJobFilter.budgetRange_eq A number or range used to filter the search by jobs having a budget equal to, more or less than, or within the values provided. For example: `[100 TO 1000]` - the budget is between 100 and 1000; `1000` - the budget is equal to 1000. `500-1000` - the budget `b` is 500 <= b <= 1000, `1000-` - the budget is >=1000; `-200` - the budget is <= 200.
days_posted marketPlaceJobFilter.daysPosted_eq Number of days since the job was posted.
paging marketPlaceJobFilter.pagination_eq Pagination, formed as `$offset;$count`. Page size is restricted to be <= 100. Example: page=20;10.
sort sortAttributes Sorts the search results by the value provided. Example: `sort=create_time%20desc`. Valid values: create_time desc, client_rating desc, client_total_charge desc, client_total_hours desc, duration desc, workload desc, create_time asc, client_rating asc, client_total_charge asc, client_total_hours asc, duration asc, workload asc
budget has multiple fields depending on the job_type: - fixed --> response.edges.node.amount - hourly --> range (response.edges.node.hourlyBudgetMin - response.edges.node.hourlyBudgetMax) Budget
category2 response.edges.node.category Category
client.country response.edges.node.client.location.country Client Country
client.feedback response.edges.node.client.totalFeedback Client Feedback
client.jobs_posted response.edges.node.client.totalPostedJobs Client Jobs Posted
client.past_hires response.edges.node.client.totalHires Client Past Hires
client.payment_verification_status response.edges.node.client.verificationStatus Client Payment Verification Status
client.reviews_count response.edges.node.client.totalReviews Client Reviews Count
date_created response.edges.node.createdDateTime Date Created
duration response.edges.node.duration Duration
id response.edges.node.ciphertext ID (Legacy)
job_status #deprecated Job Status
job_type response.edges.node.job.contractTerms.contractType Job Type
skills response.edges.node.skills Skills
snippet response.edges.node.description Snippet
subcategory2 response.edges.node.subcategory Subcategory
title response.edges.node.title Title
url Missing, but can be constructed using ${(stage.)?upwork.com/jobs/ + response.edges.node.ciphertext} URL
workload response.edges.node.job.contractTerms.hourlyContractTerms.engagementType Workload

List jobs

This call returns all jobs that a user has `manage_recruiting` access to. It can be used to find the reference/key ID of a specific job.

REST
GET  /api/hr/v2/jobs.{format} 
GraphQL
{
    organization {
        jobPosting(
          jobPostingFilter: {
            postByTeamIds_any: $postByTeamIds_any
            postByPersonIds_any: $postByPersonIds_any
            statusAndAccess_any: $statusAndAccess_any
            createdDateTimeFrom_eq: $createdDateTimeFrom_eq
            createdDateTimeTo_eq: $createdDateTimeTo_eq
            pagination_eq: $pagination_eq
        }, sortAttribute: $sortAttribute) {
            edges {
                node {
                    id
                    attachment {
                        link
                    }
                    info {
                        status
                        hourlyBudgetMin {
                            rawValue
                        }
                        hourlyBudgetMax {
                            rawValue
                        }
                        auditTime {
                            createdDateTime
                        }
                        filledDateTime
                        legacyCiphertext
                        keepOpenOnHire
                        siteSource
                    }
                    content {
                        title
                        description
                    }
                    contractTerms {
                        fixedPriceContractTerms {
                            engagementDuration {
                                id
                                weeks
                                label
                            }
                        }
                        hourlyContractTerms {
                            engagementDuration {
                                id
                                weeks
                                label
                            } 
                        }
                        contractStartDate
                        contractEndDate
                        contractType
                    }
                    ownership {
                        company {
                            id
                            rid
                            name
                        }
                        team {
                            id
                            rid
                            name
                        }
                    }
                    classification {
                        category {
                            id
                            name
                        }
                        skills {
                            id
                            prettyName
                        }
                        subCategory {
                            id
                            name
                        }
                    }
                    contractorSelection {
                        qualification {
                            contractorType
                        }
                    }
                    visibility
                }
            }
        }
    }
}
Variables
{
  "pagination_eq": {"after": "xyz789", "first": 987},
  "title_eq": "abc123",
  "postByTeamIds_any": ["4"],
  "postByPersonIds_any": ["4"],
  "statusAndAccess_any": [
    {"statuses_any": ["REQUESTED"], "accesses_any": ["PUBLIC_INDEX"]}
  ],
  "excludePostByPersonIds_any": ["4"],
  "categoryGroupIds_any": [4],
  "contractType_eq": "HOURLY",
  "createdDateTimeFrom_eq": "xyz789",
  "createdDateTimeTo_eq": "abc123"
}

Fields:

REST Field GraphQL Path Description
buyer_team__reference auto filled from the context organization The reference ID of the client's team. Example: `34567`. You can get it from List teams API call.
include_sub_teams Included by default and need to use jobPostingFilter.postByTeamIds_any to filter for specific teams If set to `1`, the response includes information about sub teams. Valid values: 0, 1
created_by jobPostingFilter.postByPersonIds_any The user ID. Example: `created_by=1234`.
status jobPostingFilter.statusAndAccess_any.statuses_any The status of the job. Valid values: open, filled, cancelled
created_time_from jobPostingFilter.createdDateTimeFrom_eq Filters by 'from' time. Example: `created_time_from=2008-09-09T00:00:01`.
created_time_to jobPostingFilter.createdDateTimeTo_eq Filters by 'to' time. Example: `created_time_to=2009-01-20T11:59:59`.
page jobPostingFilter.pagination_eq Pagination, formed as `$offset;$count`. Example: `page=20;10`
order_by sortAttribute Sorts results by the value defined. Example: `order_by=created_time`.
jobs.attachment_file_url response.edges.node.attachment.link Attachment File URL
jobs.budget response.edges.node.info.hourlyBudgetMin - response.edges.node.info.hourlyBudgetMax Budget
jobs.buyer_company__name response.edges.node.ownership.company.name Buyer Company Name
jobs.buyer_company__reference response.edges.node.ownership.company.rid or response.edges.node.ownership.company.id Buyer Company Reference
jobs.buyer_team__name response.edges.node.ownership.team.name Buyer Team Name
jobs.buyer_team__reference response.edges.node.ownership.team.rid or response.edges.node.ownership.team.id Buyer Team Reference
jobs.cancelled_date Missing, the upstream response doesn't contain the field Cancelled Date
jobs.category2 response.edges.node.classification.category Category
jobs.created_time response.edges.node.info.auditTime.createdDateTime Created Time
jobs.description response.edges.node.content.description Description
jobs.duration response.edges.node.contractTerms.fixedPriceContractTerms.engagementDuration response.edges.node.contractTerms.hourlyContractTerms.engagementDuration Duration
jobs.end_date response.edges.node.contractTerms.contractEndDate End Date
jobs.filled_date response.edges.node.info.filledDateTime Filled Date
jobs.job_ref_ciphertext response.edges.node.info.legacyCiphertext Job Reference Ciphertext
jobs.job_type response.edges.node.contractTerms.contractType Job Type
jobs.keep_open_on_hire response.edges.node.info.keepOpenOnHire Keep Open on Hire
jobs.preference_candidate_type response.edges.node.contractorSelection.qualification.contractorType Preference Candidate Type
jobs.public_url Missing, but can be constructed from response.edges.node.info.legacyCiphertext Public URL
jobs.reference response.edges.node.info.legacyCiphertext Reference
jobs.skills response.edges.node.classification.skills Skills
jobs.start_date response.edges.node.contractTerms.contractStartDate Start Date
jobs.status response.edges.node.info.status Status
jobs.subcategory2 response.edges.node.classification.subCategory Subcategory
jobs.title response.edges.node.content.title Title

Get job by key

This call returns the complete job object by job key. It's only available for users with `manage_recruiting` permissions within the team that the job is posted in.

REST
GET  /api/hr/v2/jobs/{job_key}.{format} 
GraphQL
{
    jobPosting(jobPostingId: $JobPostingId) {
        id
        attachment {
            link
        }
        info {
            status
            hourlyBudgetMin {
                rawValue
            }
            hourlyBudgetMax {
                rawValue
            }
            auditTime {
                createdDateTime
            }
            filledDateTime
            legacyCiphertext
            keepOpenOnHire
            siteSource
        }
        content {
            title
            description
        }
        contractTerms {
            fixedPriceContractTerms {
                engagementDuration {
                    id
                    weeks
                    label
                }
            }
            hourlyContractTerms {
                engagementDuration {
                    id
                    weeks
                    label
                } 
            }
            contractStartDate
            contractEndDate
            contractType
        }
        ownership {
            company {
                id
                rid
                name
            }
            team {
                id
                rid
                name
            }
        }
        classification {
            category {
                id
                name
            }
            skills {
                id
                prettyName
            }
            subCategory {
                id
                name
            }
        }
        contractorSelection {
            qualification {
                contractorType
            }
        }
        visibility
    }
}
Variables
{"jobPostingId": 4}

Fields:

REST Field GraphQL Path
job_key jobPostingId
jobs.attachment_file_url response.edges.node.attachment.link
jobs.budget response.edges.node.info.hourlyBudgetMin - response.edges.node.info.hourlyBudgetMax
jobs.buyer_company__name response.edges.node.ownership.company.name
jobs.buyer_company__reference response.edges.node.ownership.company.rid or response.edges.node.ownership.company.id
jobs.buyer_team__name response.edges.node.ownership.team.name
jobs.buyer_team__reference response.edges.node.ownership.team.rid or response.edges.node.ownership.team.id
jobs.cancelled_date Missing, the upstream response doesn't contain the field
jobs.category2 response.edges.node.classification.category
jobs.created_time response.edges.node.info.auditTime.createdDateTime
jobs.description response.edges.node.content.description
jobs.duration response.edges.node.contractTerms.fixedPriceContractTerms.engagementDuration response.edges.node.contractTerms.hourlyContractTerms.engagementDuration
jobs.end_date response.edges.node.contractTerms.contractEndDate
jobs.filled_date response.edges.node.info.filledDateTime
jobs.job_type response.edges.node.contractTerms.contractType
jobs.keep_open_on_hire response.edges.node.info.keepOpenOnHire
jobs.preference_candidate_type response.edges.node.contractorSelection.qualification.contractorType
jobs.public_url Missing, but can be constructed from response.edges.node.info.legacyCiphertext
jobs.skills response.edges.node.classification.skills
jobs.start_date response.edges.node.contractTerms.contractStartDate
jobs.status response.edges.node.info.status
jobs.subcategory2 response.edges.node.classification.subCategory
jobs.title response.edges.node.content.title
jobs.visibility response.edges.node.visibility

Snapshots

GraphQL OAuth2 scopes:

Name Description
Read snapshots information Scope to read snapshots information.

Get snapshot by Contract

Gets a specific snapshot

REST
GET  /api/team/v3/snapshots/contracts/{contract_id}/{timestamp}.{format} 
GraphQL
query ($contractId: contractId, $timestamp: timestamp) {
  snapshotsByContractId(input: {contractId: $contractId, timestamp: $timestamp}) {
    id
    contractId
    time
    screenshotImageMedium
    screenshotImage
    memo
    screenshotImageThumbnail
    webcamImageThumbnail
    companyId
    keyboardEventsCount
    minutes {
      minute {
        mouse
        keyboard
        time
      }
    }
    hasWebcam
    teamName
    webcamImage
    activeWindowTitle
    hasScreenshot
    task
    mouseEventsCount
    webcamUrl
    screenshotUrl
    status
    screenshotImageLarge
  }
}
Variables
{"contractId": "123456", "timestamp": "123456"}

Fields:

REST Field GraphQL Path
uid Snapshot.id
time Snapshot.time
contractId Snapshot.contractId
mouseEventsCount Snapshot.mouseEventsCount
keyboardEventsCount Snapshot.keyboardEventsCount
teamName Snapshot.teamName
status SnapshotStatus
activeWindowTitle Snapshot.activeWindowTitle
memo Snapshot.memo
companyId Snapshot.companyId
hasScreenshot Snapshot.hasScreenshot
screenshotUrl SnapshotScreenshotUrl
screenshotImg SnapshotScreenshotImage
screenshotImgLrg SnapshotScreenshotImageLarge
screenshotImgMed SnapshotScreenshotImageMedium
screenshotImgThmb SnapshotScreenshotImageThumbnail
hasCamerashot Snapshot.hasWebcam
webcamUrl Snapshot.webcamUrl
webcamImg Snapshot.webcamImage
webcamImgThmb Snapshot.webcamImageThumbnail
task Snapshot.task
minutes.time Snapshot.minutes.time
minutes.mouse Snapshot.minutes.mouse
minutes.keyboard Snapshot.minutes.keyboard
workdiary_api Deprecated

Operations

Common Information

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.

Error handling in GraphQL

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.

For example, the following API query returned the status code: 200 - OK. Let's see how the message, locations, and extensions parameters in the body help you understand the status of the API call.

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

When you do not have Oauth2 permissions or scopes to access the endpoint

Query request:
          {
            user {
              id
              nid
              rid
              name
              email
            }
            organization {
              id
              rid
            }
          }
                
Error response:
          {
            "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]."
              }
            ]
          }
                

When you do not specify any value for a required field

Query request:
          {
            user {
              companyFees(organizationId: null, input: { amount: "15" }) {
                amount
                fullAmount
                fees {
                  type
                  description
                  calculationDescription
                  rate
                  amount
                }
              }
            }
          }
                
Error response:
          {
            "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"
                }
              }
            ]
          }
          
                

When you do not define a parameter

Query request:
          {
            user {
              stepUpVerification
            }
          }
                
Error response:
          {
            "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:

  • Java
  • PHP
  • Python 3
  • Node JS
  • Ruby
  • Go

SDKs return the GraphQL error responses similar to APIs and do not handle them any differently.

Queries

Proposals

clientProposal

Description

client proposal by ID

Response

Returns a ClientProposal

Arguments
Name Description
id - ID!

Example

Query
query clientProposal($id: ID!) {
  clientProposal(id: $id) {
    id
    user {
      ...GenericUserFragment
    }
    organization {
      ...GenericOrganizationFragment
    }
    job {
      ...MarketplaceJobPostingFragment
    }
    terms {
      ...ProposalTermsFragment
    }
    coverLetter
    projectPlan {
      ...ProposalProjectPlanFragment
    }
    status {
      ...ClientProposalStatusFragment
    }
    annotations
  }
}
Variables
{"id": "4"}
Response
{
  "data": {
    "clientProposal": {
      "id": 4,
      "user": GenericUser,
      "organization": GenericOrganization,
      "job": MarketplaceJobPosting,
      "terms": ProposalTerms,
      "coverLetter": "xyz789",
      "projectPlan": ProposalProjectPlan,
      "status": ClientProposalStatus,
      "annotations": ["Recommended"]
    }
  }
}

clientProposals

Description

search client proposal

Response

Returns a ClientProposalsConnection

Arguments
Name Description
jobPostingId - ID!
filter - ClientProposalFilter
sortAttribute - ClientProposalSortAttribute
pagination - Pagination

Example

Query
query clientProposals(
  $jobPostingId: ID!,
  $filter: ClientProposalFilter,
  $sortAttribute: ClientProposalSortAttribute,
  $pagination: Pagination
) {
  clientProposals(
    jobPostingId: $jobPostingId,
    filter: $filter,
    sortAttribute: $sortAttribute,
    pagination: $pagination
  ) {
    totalCount
    edges {
      ...ClientProposalsEdgeFragment
    }
    pageInfo {
      ...PageInfoFragment
    }
  }
}
Variables
{
  "jobPostingId": "4",
  "filter": ClientProposalFilter,
  "sortAttribute": ClientProposalSortAttribute,
  "pagination": Pagination
}
Response
{
  "data": {
    "clientProposals": {
      "totalCount": 123,
      "edges": [ClientProposalsEdge],
      "pageInfo": PageInfo
    }
  }
}

proposalMetadata

Description

metadata for proposals

Response

Returns a ProposalMetadata

Example

Query
query proposalMetadata {
  proposalMetadata {
    engagementDurationValues {
      ...ProposalEngagementDurationFragment
    }
    reasons {
      ...ReasonsMetadataFragment
    }
  }
}
Response
{
  "data": {
    "proposalMetadata": {
      "engagementDurationValues": [
        ProposalEngagementDuration
      ],
      "reasons": [ReasonsMetadata]
    }
  }
}

vendorProposal

Description

vendor proposal by ID

Response

Returns a VendorProposal

Arguments
Name Description
id - ID!

Example

Query
query vendorProposal($id: ID!) {
  vendorProposal(id: $id) {
    id
    user {
      ...GenericUserFragment
    }
    organization {
      ...GenericOrganizationFragment
    }
    marketplaceJobPosting {
      ...MarketplaceJobPostingFragment
    }
    terms {
      ...ProposalTermsFragment
    }
    coverLetter
    proposalCoverLetter
    projectPlan {
      ...ProposalProjectPlanFragment
    }
    status {
      ...VendorProposalStatusFragment
    }
    annotations
  }
}
Variables
{"id": 4}
Response
{
  "data": {
    "vendorProposal": {
      "id": "4",
      "user": GenericUser,
      "organization": GenericOrganization,
      "marketplaceJobPosting": MarketplaceJobPosting,
      "terms": ProposalTerms,
      "coverLetter": "xyz789",
      "proposalCoverLetter": "xyz789",
      "projectPlan": ProposalProjectPlan,
      "status": VendorProposalStatus,
      "annotations": ["Hidden"]
    }
  }
}

vendorProposals

Description

list of vendor proposals based on filters like job posting ids, vendor id, etc

Response

Returns a VendorProposalsConnection!

Arguments
Name Description
filter - VendorProposalFilter!
sortAttribute - VendorProposalSortAttribute!
pagination - Pagination!

Example

Query
query vendorProposals(
  $filter: VendorProposalFilter!,
  $sortAttribute: VendorProposalSortAttribute!,
  $pagination: Pagination!
) {
  vendorProposals(
    filter: $filter,
    sortAttribute: $sortAttribute,
    pagination: $pagination
  ) {
    totalCount
    edges {
      ...VendorProposalsEdgeFragment
    }
    pageInfo {
      ...PageInfoFragment
    }
  }
}
Variables
{
  "filter": VendorProposalFilter,
  "sortAttribute": VendorProposalSortAttribute,
  "pagination": Pagination
}
Response
{
  "data": {
    "vendorProposals": {
      "totalCount": 987,
      "edges": [VendorProposalsEdge],
      "pageInfo": PageInfo
    }
  }
}
Offers and Contracts

contract

Response

Returns a Contract

Arguments
Name Description
id - ID!

Example

Query
query contract($id: ID!) {
  contract(id: $id) {
    id
    title
    contractType
    job {
      ...MarketplaceJobPostingFragment
    }
    hasAgency
    offer {
      ...OfferFragment
    }
    clientProposal {
      ...ClientProposalFragment
    }
    weeklyChargeAmount {
      ...MoneyFragment
    }
    weeklyHoursLimit
    hourlyChargeRate {
      ...MoneyFragment
    }
    createdDateTime
    firstContractStartDateTime
    modifiedDateTime
    startDateTime
    endDateTime
    manualTimeAllowed
    hideScreenshots
    last
    weeklyStipendHours
    estimatedDuration {
      ...ProposalEngagementDurationFragment
    }
    status
    suspended
    freelancer {
      ...FreelancerProfileFragment
    }
    paused
    clientCompany {
      ...PublicCompanyInfoFragment
    }
    milestones {
      ...MilestoneFragment
    }
    workDays {
      ...WorkDayFragment
    }
    workDiaryTimeCells {
      ...WorkDiaryTimeCellFragment
    }
    feedback {
      ...FeedbackFragment
    }
  }
}
Variables
{"id": "4"}
Response
{
  "data": {
    "contract": {
      "id": 4,
      "title": "abc123",
      "contractType": "HOURLY",
      "job": MarketplaceJobPosting,
      "hasAgency": true,
      "offer": Offer,
      "clientProposal": ClientProposal,
      "weeklyChargeAmount": Money,
      "weeklyHoursLimit": 987.65,
      "hourlyChargeRate": Money,
      "createdDateTime": "abc123",
      "firstContractStartDateTime": "abc123",
      "modifiedDateTime": "abc123",
      "startDateTime": "abc123",
      "endDateTime": "abc123",
      "manualTimeAllowed": true,
      "hideScreenshots": true,
      "last": true,
      "weeklyStipendHours": 987.65,
      "estimatedDuration": ProposalEngagementDuration,
      "status": "ACTIVE",
      "suspended": false,
      "freelancer": FreelancerProfile,
      "paused": false,
      "clientCompany": PublicCompanyInfo,
      "milestones": [Milestone],
      "workDays": [WorkDay],
      "workDiaryTimeCells": [WorkDiaryTimeCell],
      "feedback": Feedback
    }
  }
}

contractByTerm

Description

get contract data by term id termId - contract term id, legacy contract assignment rid. required date - date in ISO format yyyy-MM-ddThh:mm+HHmm or yyyy-MM-dd, optional

Response

Returns a ContractDetails!

Arguments
Name Description
termId - ID!
date - String

Example

Query
query contractByTerm(
  $termId: ID!,
  $date: String
) {
  contractByTerm(
    termId: $termId,
    date: $date
  ) {
    id
    title
    status
    closingReason {
      ...ClosingReasonFragment
    }
    deliveryModel
    kind
    isPtc
    createDate
    modifyDate
    startDate
    endDate
    offer {
      ...OfferFragment
    }
    job {
      ...JobPostingFragment
    }
    freelancer {
      ...ContractUserFragment
    }
    vendorOrganization {
      ...GenericOrganizationFragment
    }
    vendorTeam {
      ...GenericOrganizationFragment
    }
    clientOrganization {
      ...GenericOrganizationFragment
    }
    clientTeam {
      ...GenericOrganizationFragment
    }
    hiringManager {
      ...ContractUserFragment
    }
    agencyManager {
      ...ContractUserFragment
    }
    supervisor {
      ...ContractUserFragment
    }
    changingUserType
    changedBy {
      ...ContractUserFragment
    }
    endedBy {
      ...ContractUserFragment
    }
    metadata {
      ...ContractMetadataFragment
    }
    hourlyLimits {
      ...HourlyLimitFragment
    }
    terms {
      ...ContractTermsFragment
    }
  }
}
Variables
{"termId": 4, "date": "abc123"}
Response
{
  "data": {
    "contractByTerm": {
      "id": 4,
      "title": "xyz789",
      "status": "ACTIVE",
      "closingReason": ClosingReason,
      "deliveryModel": "TALENT_MARKETPLACE",
      "kind": "WEEKLY_RETAINER",
      "isPtc": true,
      "createDate": "abc123",
      "modifyDate": "xyz789",
      "startDate": "abc123",
      "endDate": "abc123",
      "offer": Offer,
      "job": JobPosting,
      "freelancer": ContractUser,
      "vendorOrganization": GenericOrganization,
      "vendorTeam": GenericOrganization,
      "clientOrganization": GenericOrganization,
      "clientTeam": GenericOrganization,
      "hiringManager": ContractUser,
      "agencyManager": ContractUser,
      "supervisor": ContractUser,
      "changingUserType": "CLIENT",
      "changedBy": ContractUser,
      "endedBy": ContractUser,
      "metadata": ContractMetadata,
      "hourlyLimits": [HourlyLimit],
      "terms": ContractTerms
    }
  }
}

contractProposal

Response

Returns a ContractProposal

Arguments
Name Description
id - ID!

Example

Query
query contractProposal($id: ID!) {
  contractProposal(id: $id) {
    id
    state
    updatedDateTime
    createdDateTime
    canClientOfferBeAccepted
  }
}
Variables
{"id": 4}
Response
{
  "data": {
    "contractProposal": {
      "id": "4",
      "state": "xyz789",
      "updatedDateTime": "xyz789",
      "createdDateTime": "xyz789",
      "canClientOfferBeAccepted": true
    }
  }
}

contractTerm

Description

get contract and single term data termId - contract term id, legacy contract assignment rid. required

Response

Returns a ContractDetails!

Arguments
Name Description
termId - ID!

Example

Query
query contractTerm($termId: ID!) {
  contractTerm(termId: $termId) {
    id
    title
    status
    closingReason {
      ...ClosingReasonFragment
    }
    deliveryModel
    kind
    isPtc
    createDate
    modifyDate
    startDate
    endDate
    offer {
      ...OfferFragment
    }
    job {
      ...JobPostingFragment
    }
    freelancer {
      ...ContractUserFragment
    }
    vendorOrganization {
      ...GenericOrganizationFragment
    }
    vendorTeam {
      ...GenericOrganizationFragment
    }
    clientOrganization {
      ...GenericOrganizationFragment
    }
    clientTeam {
      ...GenericOrganizationFragment
    }
    hiringManager {
      ...ContractUserFragment
    }
    agencyManager {
      ...ContractUserFragment
    }
    supervisor {
      ...ContractUserFragment
    }
    changingUserType
    changedBy {
      ...ContractUserFragment
    }
    endedBy {
      ...ContractUserFragment
    }
    metadata {
      ...ContractMetadataFragment
    }
    hourlyLimits {
      ...HourlyLimitFragment
    }
    terms {
      ...ContractTermsFragment
    }
  }
}
Variables
{"termId": 4}
Response
{
  "data": {
    "contractTerm": {
      "id": "4",
      "title": "xyz789",
      "status": "ACTIVE",
      "closingReason": ClosingReason,
      "deliveryModel": "TALENT_MARKETPLACE",
      "kind": "WEEKLY_RETAINER",
      "isPtc": false,
      "createDate": "xyz789",
      "modifyDate": "xyz789",
      "startDate": "abc123",
      "endDate": "abc123",
      "offer": Offer,
      "job": JobPosting,
      "freelancer": ContractUser,
      "vendorOrganization": GenericOrganization,
      "vendorTeam": GenericOrganization,
      "clientOrganization": GenericOrganization,
      "clientTeam": GenericOrganization,
      "hiringManager": ContractUser,
      "agencyManager": ContractUser,
      "supervisor": ContractUser,
      "changingUserType": "CLIENT",
      "changedBy": ContractUser,
      "endedBy": ContractUser,
      "metadata": ContractMetadata,
      "hourlyLimits": [HourlyLimit],
      "terms": ContractTerms
    }
  }
}

customFields

Description

custom fields information

Response

Returns [CustomFields!]

Arguments
Name Description
input - CustomFieldsInput!
offset - Int
limit - Int

Example

Query
query customFields(
  $input: CustomFieldsInput!,
  $offset: Int,
  $limit: Int
) {
  customFields(
    input: $input,
    offset: $offset,
    limit: $limit
  ) {
    responseId
    id
    itemId
    typeSnap
    labelSnap
    displayValueSnap
    creator {
      ...GenericUserFragment
    }
    createdDateTime {
      ...DateTimeFragment
    }
    rollupAssignmentId
    firstContractId
    offerId
    jobPostingId
    byoInvitationId
    buyItNowId
    questionnaireResponsesId
    stale
    termSectionId
    aclSnap
  }
}
Variables
{"input": CustomFieldsInput, "offset": 987, "limit": 987}
Response
{
  "data": {
    "customFields": [
      {
        "responseId": 4,
        "id": 4,
        "itemId": 4,
        "typeSnap": "TEXT_FIELD",
        "labelSnap": "xyz789",
        "displayValueSnap": "xyz789",
        "creator": GenericUser,
        "createdDateTime": DateTime,
        "rollupAssignmentId": "4",
        "firstContractId": "4",
        "offerId": "4",
        "jobPostingId": "4",
        "byoInvitationId": 4,
        "buyItNowId": "4",
        "questionnaireResponsesId": 4,
        "stale": true,
        "termSectionId": "4",
        "aclSnap": "xyz789"
      }
    ]
  }
}

offer

Description

Returns offer for the given id

Response

Returns an Offer

Arguments
Name Description
id - ID!

Example

Query
query offer($id: ID!) {
  offer(id: $id) {
    id
    title
    description
    type
    job {
      ...MarketplaceJobPostingFragment
    }
    vendorProposal {
      ...VendorProposalFragment
    }
    closeJobPostingOnAccept
    client {
      ...GenericOrganizationFragment
    }
    offerTerms {
      ...OfferTermsFragment
    }
    messageToContractor
    state
    offerFeatures {
      ...OfferFeaturesFragment
    }
    clientCompany {
      ...PublicCompanyInfoFragment
    }
    milestones {
      ...MilestoneFragment
    }
    createdUsingBYOFlow
    freelancer {
      ...FreelancerProfileFragment
    }
    payrollOffer
    customFields {
      ...CustomFieldsConnectionFragment
    }
  }
}
Variables
{"id": "4"}
Response
{
  "data": {
    "offer": {
      "id": "4",
      "title": "abc123",
      "description": "abc123",
      "type": "MARKET_PLACE_HOURLY",
      "job": MarketplaceJobPosting,
      "vendorProposal": VendorProposal,
      "closeJobPostingOnAccept": true,
      "client": GenericOrganization,
      "offerTerms": OfferTerms,
      "messageToContractor": "xyz789",
      "state": "DRAFT",
      "offerFeatures": OfferFeatures,
      "clientCompany": PublicCompanyInfo,
      "milestones": [Milestone],
      "createdUsingBYOFlow": false,
      "freelancer": FreelancerProfile,
      "payrollOffer": true,
      "customFields": CustomFieldsConnection
    }
  }
}

offersByAttribute

Description

Get offers by search attribute and id. filter - contains data for searching

Response

Returns an OfferList

Arguments
Name Description
filter - SearchOffersInput!

Example

Query
query offersByAttribute($filter: SearchOffersInput!) {
  offersByAttribute(filter: $filter) {
    offers {
      ...OfferFragment
    }
  }
}
Variables
{"filter": SearchOffersInput}
Response
{"data": {"offersByAttribute": {"offers": [Offer]}}}

offersByIds

Description

Get offers by ids. filter - contains data for searching

Response

Returns an OfferList

Arguments
Name Description
filter - SearchOffersByIdInput!

Example

Query
query offersByIds($filter: SearchOffersByIdInput!) {
  offersByIds(filter: $filter) {
    offers {
      ...OfferFragment
    }
  }
}
Variables
{"filter": SearchOffersByIdInput}
Response
{"data": {"offersByIds": {"offers": [Offer]}}}

vendorContracts

Description

get list of contracts associated with a specific vendor

Response

Returns a ContractSearchResults

Arguments
Name Description
filter - VendorContractSearchFilter!
options - ContractOptionsInput
paging - ContractPagingInput

Example

Query
query vendorContracts(
  $filter: VendorContractSearchFilter!,
  $options: ContractOptionsInput,
  $paging: ContractPagingInput
) {
  vendorContracts(
    filter: $filter,
    options: $options,
    paging: $paging
  ) {
    paging {
      ...ContractPagingFragment
    }
    contracts {
      ...ContractDetailsFragment
    }
  }
}
Variables
{
  "filter": VendorContractSearchFilter,
  "options": ContractOptionsInput,
  "paging": ContractPagingInput
}
Response
{
  "data": {
    "vendorContracts": {
      "paging": ContractPaging,
      "contracts": [ContractDetails]
    }
  }
}
Reporting

contractTimeReport

Response

Returns a TimeReportConnection!

Arguments
Name Description
filter - TimeReportFilter
pagination - Pagination

Example

Query
query contractTimeReport(
  $filter: TimeReportFilter,
  $pagination: Pagination
) {
  contractTimeReport(
    filter: $filter,
    pagination: $pagination
  ) {
    totalCount
    edges {
      ...TimeReportEdgeFragment
    }
    pageInfo {
      ...PageInfoFragment
    }
  }
}
Variables
{
  "filter": TimeReportFilter,
  "pagination": Pagination
}
Response
{
  "data": {
    "contractTimeReport": {
      "totalCount": 123,
      "edges": [TimeReportEdge],
      "pageInfo": PageInfo
    }
  }
}

timeReport

use contractTimeReport instead
Description

Get the time report details for the given time range and a given organization

Response

Returns [TimeReport!]

Arguments
Name Description
filter - TimeReportFilter

Example

Query
query timeReport($filter: TimeReportFilter) {
  timeReport(filter: $filter) {
    dateWorkedOn
    weekWorkedOn
    monthWorkedOn
    yearWorkedOn
    freelancer {
      ...GenericUserFragment
    }
    team {
      ...GenericOrganizationFragment
    }
    contractOffer {
      ...ContractOfferResultFragment
    }
    contract {
      ...ContractDetailsFragment
    }
    termId
    task
    taskDescription
    memo
    totalHoursWorked
    totalCharges
    totalOnlineHoursWorked
    totalOnlineCharge
    totalOfflineHoursWorked
    totalOfflineCharge
    billRate {
      ...BillRateFragment
    }
  }
}
Variables
{"filter": TimeReportFilter}
Response
{
  "data": {
    "timeReport": [
      {
        "dateWorkedOn": "xyz789",
        "weekWorkedOn": "xyz789",
        "monthWorkedOn": "xyz789",
        "yearWorkedOn": "xyz789",
        "freelancer": GenericUser,
        "team": GenericOrganization,
        "contractOffer": ContractOfferResult,
        "contract": ContractDetails,
        "termId": "4",
        "task": "xyz789",
        "taskDescription": "xyz789",
        "memo": "abc123",
        "totalHoursWorked": 987.65,
        "totalCharges": 123.45,
        "totalOnlineHoursWorked": 123.45,
        "totalOnlineCharge": 987.65,
        "totalOfflineHoursWorked": 987.65,
        "totalOfflineCharge": 987.65,
        "billRate": BillRate
      }
    ]
  }
}

transactionHistory

Description

Returns some total data about the entire set of transactions. Result also includes groups of pending transactions, if available.

Response

Returns a TransactionHistory

Arguments
Name Description
transactionHistoryFilter - TransactionHistoryFilter

Example

Query
query transactionHistory($transactionHistoryFilter: TransactionHistoryFilter) {
  transactionHistory(transactionHistoryFilter: $transactionHistoryFilter) {
    transactionDetail {
      ...TransactionHistoryDetailFragment
    }
  }
}
Variables
{"transactionHistoryFilter": TransactionHistoryFilter}
Response
{
  "data": {
    "transactionHistory": {
      "transactionDetail": TransactionHistoryDetail
    }
  }
}
Job Posts

jobPosting

Response

Returns a JobPosting!

Arguments
Name Description
jobPostingId - ID!
loadAnnotation - Boolean

Example

Query
query jobPosting(
  $jobPostingId: ID!,
  $loadAnnotation: Boolean
) {
  jobPosting(
    jobPostingId: $jobPostingId,
    loadAnnotation: $loadAnnotation
  ) {
    id
    info {
      ...JobPostingInfoFragment
    }
    visibility
    ownership {
      ...JobPostingOwnershipFragment
    }
    content {
      ...JobPostingContentFragment
    }
    attachment {
      ...JobPostingAttachmentFragment
    }
    classification {
      ...JobPostingClassificationFragment
    }
    segmentationData {
      ...JobPostingSegmentationDataFragment
    }
    contractTerms {
      ...JobPostingContractTermsFragment
    }
    contractorSelection {
      ...JobPostingContractorSelectionFragment
    }
    additionalInfo {
      ...JobPostingAdditionalInfoFragment
    }
    ptcInfo {
      ...JobPostingPtcInfoFragment
    }
    proposalsStatistics {
      ...ProposalsStatisticsFragment
    }
    customFields {
      ...JobPostingCustomFieldsFragment
    }
  }
}
Variables
{
  "jobPostingId": "4",
  "loadAnnotation": false
}
Response
{
  "data": {
    "jobPosting": {
      "id": "4",
      "info": JobPostingInfo,
      "visibility": "PUBLIC_INDEX",
      "ownership": JobPostingOwnership,
      "content": JobPostingContent,
      "attachment": [JobPostingAttachment],
      "classification": JobPostingClassification,
      "segmentationData": JobPostingSegmentationData,
      "contractTerms": JobPostingContractTerms,
      "contractorSelection": JobPostingContractorSelection,
      "additionalInfo": JobPostingAdditionalInfo,
      "ptcInfo": JobPostingPtcInfo,
      "proposalsStatistics": ProposalsStatistics,
      "customFields": [JobPostingCustomFields]
    }
  }
}

jobsFeaturePredictions

Description

The prediction models of a set of jobs

Response

Returns [JobFeaturePrediction!]!

Arguments
Name Description
ids - [ID!]!

Example

Query
query jobsFeaturePredictions($ids: [ID!]!) {
  jobsFeaturePredictions(ids: $ids) {
    id
    openingMultiFreelancerPrediction
    opening
  }
}
Variables
{"ids": ["4"]}
Response
{
  "data": {
    "jobsFeaturePredictions": [
      {
        "id": 4,
        "openingMultiFreelancerPrediction": true,
        "opening": "xyz789"
      }
    ]
  }
}

marketplaceJobPosting

Response

Returns a MarketplaceJobPosting

Arguments
Name Description
id - ID!

Example

Query
query marketplaceJobPosting($id: ID!) {
  marketplaceJobPosting(id: $id) {
    id
    workFlowState {
      ...MarketplacePostingWorkFlowStateFragment
    }
    ownership {
      ...MarketplacePostingOwnershipFragment
    }
    annotations {
      ...MarketplacePostingAnnotationsFragment
    }
    activityStat {
      ...MarketplacePostingActivityStatFragment
    }
    content {
      ...MarketplaceJobPostingContentFragment
    }
    attachments {
      ...MarketplacePostingAttachmentFragment
    }
    classification {
      ...MarketplacePostingClassificationFragment
    }
    segmentationData {
      ...MarketplaceSegmentationDataFragment
    }
    contractTerms {
      ...MarketplaceContractTermsFragment
    }
    contractorSelection {
      ...MarketplaceContractorSelectionFragment
    }
    additionalSearchInfo {
      ...MarketplaceAdditionalSearchInfoFragment
    }
    clientCompany {
      ...PrivateCompanyInfoFragment
    }
    clientCompanyPublic {
      ...MarketplacePublicCompanyInfoFragment
    }
    canClientReceiveContractProposal
    clientProposals {
      ...ClientProposalsConnectionFragment
    }
    customFields {
      ...CustomFieldsConnectionFragment
    }
  }
}
Variables
{"id": "4"}
Response
{
  "data": {
    "marketplaceJobPosting": {
      "id": 4,
      "workFlowState": MarketplacePostingWorkFlowState,
      "ownership": MarketplacePostingOwnership,
      "annotations": MarketplacePostingAnnotations,
      "activityStat": MarketplacePostingActivityStat,
      "content": MarketplaceJobPostingContent,
      "attachments": [MarketplacePostingAttachment],
      "classification": MarketplacePostingClassification,
      "segmentationData": MarketplaceSegmentationData,
      "contractTerms": MarketplaceContractTerms,
      "contractorSelection": MarketplaceContractorSelection,
      "additionalSearchInfo": MarketplaceAdditionalSearchInfo,
      "clientCompany": PrivateCompanyInfo,
      "clientCompanyPublic": MarketplacePublicCompanyInfo,
      "canClientReceiveContractProposal": false,
      "clientProposals": ClientProposalsConnection,
      "customFields": CustomFieldsConnection
    }
  }
}

marketplaceJobPostings

Arguments
Name Description
marketPlaceJobFilter - MarketplaceJobFilter
searchType - MarketplaceJobPostingSearchType
sortAttributes - [MarketplaceJobPostingSearchSortAttribute]

Example

Query
query marketplaceJobPostings(
  $marketPlaceJobFilter: MarketplaceJobFilter,
  $searchType: MarketplaceJobPostingSearchType,
  $sortAttributes: [MarketplaceJobPostingSearchSortAttribute]
) {
  marketplaceJobPostings(
    marketPlaceJobFilter: $marketPlaceJobFilter,
    searchType: $searchType,
    sortAttributes: $sortAttributes
  ) {
    totalCount
    edges {
      ...MarketplaceJobpostingSearchEdgeFragment
    }
    pageInfo {
      ...PageInfoFragment
    }
  }
}
Variables
{
  "marketPlaceJobFilter": MarketplaceJobFilter,
  "searchType": "USER_JOBS_SEARCH",
  "sortAttributes": [
    MarketplaceJobPostingSearchSortAttribute
  ]
}
Response
{
  "data": {
    "marketplaceJobPostings": {
      "totalCount": 987,
      "edges": [MarketplaceJobpostingSearchEdge],
      "pageInfo": PageInfo
    }
  }
}

marketplaceJobPostingsContents

Arguments
Name Description
ids - [ID!]!

Example

Query
query marketplaceJobPostingsContents($ids: [ID!]!) {
  marketplaceJobPostingsContents(ids: $ids) {
    id
    ciphertext
    title
    description
    publishedDateTime
    annotations {
      ...MarketplacePostingAnnotationsFragment
    }
  }
}
Variables
{"ids": [4]}
Response
{
  "data": {
    "marketplaceJobPostingsContents": [
      {
        "id": "4",
        "ciphertext": "abc123",
        "title": "abc123",
        "description": "xyz789",
        "publishedDateTime": "xyz789",
        "annotations": MarketplacePostingAnnotations
      }
    ]
  }
}
Users and teams

accountAuditRecord

Description

Audit information of the account management action

Response

Returns an AccountAuditRecord

Arguments
Name Description
processInstanceId - ID!

Example

Query
query accountAuditRecord($processInstanceId: ID!) {
  accountAuditRecord(processInstanceId: $processInstanceId) {
    processInstanceId
    status
    metadata {
      ...StringMapElementFragment
    }
  }
}
Variables
{"processInstanceId": "4"}
Response
{
  "data": {
    "accountAuditRecord": {
      "processInstanceId": 4,
      "status": "abc123",
      "metadata": [StringMapElement]
    }
  }
}

company

Response

Returns a CompanyInfo

Arguments
Name Description
id - ID!

Example

Query
query company($id: ID!) {
  company(id: $id) {
    public {
      ...PublicCompanyInfoFragment
    }
    private {
      ...PrivateCompanyInfoFragment
    }
  }
}
Variables
{"id": "4"}
Response
{
  "data": {
    "company": {
      "public": PublicCompanyInfo,
      "private": PrivateCompanyInfo
    }
  }
}

companySelector

Description

Company selector provides information on companies that user can select

Response

Returns a CompanySelector!

Example

Query
query companySelector {
  companySelector {
    items {
      ...CompanySelectorItemFragment
    }
  }
}
Response
{
  "data": {
    "companySelector": {"items": [CompanySelectorItem]}
  }
}

freelancerProfileByProfileKey

Description

Retrieve freelancer profile by the freelancer profile key(ciphertext)

Response

Returns a FreelancerProfile!

Arguments
Name Description
profileKey - String!

Example

Query
query freelancerProfileByProfileKey($profileKey: String!) {
  freelancerProfileByProfileKey(profileKey: $profileKey) {
    user {
      ...CurrentUserFragment
    }
    personalData {
      ...FreelancerProfilePersonalDataFragment
    }
    userPreferences {
      ...FreelancerProfileUserPreferencesFragment
    }
    employmentRecords {
      ...FreelancerProfileEmploymentRecordFragment
    }
    availability {
      ...FreelancerProfileAvailabilityFragment
    }
    aggregates {
      ...FreelancerProfileAggregatesFragment
    }
    profileCompletenessSummary {
      ...FreelancerProfileCompletenessSummaryFragment
    }
    linkedExternalAccountsList {
      ...FreelancerProfileLinkedExternalAccountsConnectionFragment
    }
    verifications {
      ...FreelancerProfileVerificationsFragment
    }
    fullName
    firstName
    lastName
    countryDetails {
      ...CountryFragment
    }
    email
    portrait {
      ...PortraitFragment
    }
    phoneNumber {
      ...PhoneNumberFragment
    }
  }
}
Variables
{"profileKey": "xyz789"}
Response
{
  "data": {
    "freelancerProfileByProfileKey": {
      "user": CurrentUser,
      "personalData": FreelancerProfilePersonalData,
      "userPreferences": FreelancerProfileUserPreferences,
      "employmentRecords": [
        FreelancerProfileEmploymentRecord
      ],
      "availability": FreelancerProfileAvailability,
      "aggregates": FreelancerProfileAggregates,
      "profileCompletenessSummary": FreelancerProfileCompletenessSummary,
      "linkedExternalAccountsList": FreelancerProfileLinkedExternalAccountsConnection,
      "verifications": FreelancerProfileVerifications,
      "fullName": "abc123",
      "firstName": "abc123",
      "lastName": "xyz789",
      "countryDetails": Country,
      "email": "xyz789",
      "portrait": Portrait,
      "phoneNumber": PhoneNumber
    }
  }
}

freelancerStats

Response

Returns a FreelancerStats

Arguments
Name Description
id - ID!

Example

Query
query freelancerStats($id: ID!) {
  freelancerStats(id: $id) {
    mainCategory90
    applicationsSent90
    applicationFitZscore90
    applicationHiddenZscore90
    viewRateZscore90
    interviewRateZscore90
    hireRateZscore90
    medianCtgPreHireApps365
    totalInvitations90
    respondedInvitations90
    invitationsRespondedIn1Day90
    totalHires
    recommendRate
    feedback360
    policyViolations360
    allSourcesAvailable
    nss100Bw
    longTermClients
    hideReasonsTop3
    profileDiscoveries {
      ...ProfileDiscoveriesFragment
    }
    topRatedStatus
    policyViolations90Limited
    nss100BwUpdatedDate
    notAvailableSources
    earnings365NoPending
    weeksEligibleWithin16wks
    topRatedPlusStatus
  }
}
Variables
{"id": 4}
Response
{
  "data": {
    "freelancerStats": {
      "mainCategory90": "xyz789",
      "applicationsSent90": 123,
      "applicationFitZscore90": 987,
      "applicationHiddenZscore90": 123,
      "viewRateZscore90": 123,
      "interviewRateZscore90": 123,
      "hireRateZscore90": 123,
      "medianCtgPreHireApps365": 987,
      "totalInvitations90": 987,
      "respondedInvitations90": 987,
      "invitationsRespondedIn1Day90": 987,
      "totalHires": 123,
      "recommendRate": "xyz789",
      "feedback360": "abc123",
      "policyViolations360": 123,
      "allSourcesAvailable": true,
      "nss100Bw": "xyz789",
      "longTermClients": 123,
      "hideReasonsTop3": ["xyz789"],
      "profileDiscoveries": ProfileDiscoveries,
      "topRatedStatus": "abc123",
      "policyViolations90Limited": 123,
      "nss100BwUpdatedDate": "abc123",
      "notAvailableSources": ["xyz789"],
      "earnings365NoPending": 987,
      "weeksEligibleWithin16wks": 123,
      "topRatedPlusStatus": "abc123"
    }
  }
}

freelancerVisibility

Description

Get the visibility status of a given freelancer profile

Response

Returns a FreelancerVisibility

Arguments
Name Description
id - ID

Example

Query
query freelancerVisibility($id: ID) {
  freelancerVisibility(id: $id) {
    locked
    risky
    currentVisibility
    originalVisibility
  }
}
Variables
{"id": "4"}
Response
{
  "data": {
    "freelancerVisibility": {
      "locked": true,
      "risky": true,
      "currentVisibility": "xyz789",
      "originalVisibility": "xyz789"
    }
  }
}

organization

Description

Current organization

Response

Returns a CurrentOrganization

Example

Query
query organization {
  organization {
    id
    rid
    legacyId
    name
    type
    legacyType
    flag {
      ...OrganizationFlagFragment
    }
    parentOrganization {
      ...CurrentOrganizationFragment
    }
    active
    hidden
    childOrganizations {
      ...CurrentOrganizationFragment
    }
    childOrganization {
      ...CurrentOrganizationFragment
    }
    company {
      ...PrivateCompanyInfoFragment
    }
    photoUrl
    creationDate
    staffs {
      ...StaffsConnectionFragment
    }
    permissions {
      ...UserPermissionsFragment
    }
    agencyOffers {
      ...ContractOfferConnectionFragment
    }
    clientOffers {
      ...ContractOfferConnectionFragment
    }
    clientTimeReport {
      ...TimeReportFragment
    }
    clientContractTimeReport {
      ...TimeReportConnectionFragment
    }
    agencyTimeReport {
      ...TimeReportFragment
    }
    agencyContractTimeReport {
      ...TimeReportConnectionFragment
    }
    privateTalentClouds {
      ...PrivateTalentCloudFragment
    }
    jobPosting {
      ...JobPostingConnectionFragment
    }
  }
}
Response
{
  "data": {
    "organization": {
      "id": 4,
      "rid": "4",
      "legacyId": 4,
      "name": "xyz789",
      "type": "BUSINESS",
      "legacyType": "CLIENT",
      "flag": OrganizationFlag,
      "parentOrganization": CurrentOrganization,
      "active": true,
      "hidden": true,
      "childOrganizations": [CurrentOrganization],
      "childOrganization": CurrentOrganization,
      "company": PrivateCompanyInfo,
      "photoUrl": "xyz789",
      "creationDate": "abc123",
      "staffs": StaffsConnection,
      "permissions": UserPermissions,
      "agencyOffers": ContractOfferConnection,
      "clientOffers": ContractOfferConnection,
      "clientTimeReport": [TimeReport],
      "clientContractTimeReport": TimeReportConnection,
      "agencyTimeReport": [TimeReport],
      "agencyContractTimeReport": TimeReportConnection,
      "privateTalentClouds": [PrivateTalentCloud],
      "jobPosting": JobPostingConnection
    }
  }
}

user

Description

Current user

Response

Returns a CurrentUser

Example

Query
query user {
  user {
    id
    nid
    rid
    email
    name
    permissions {
      ...UserPermissionsFragment
    }
    photoUrl
    offer {
      ...ContractOfferConnectionFragment
    }
    timeReport {
      ...TimeReportFragment
    }
    contractTimeReport {
      ...TimeReportConnectionFragment
    }
    freelancerProfile {
      ...FreelancerProfileFragment
    }
    ciphertext
    i18NSettings {
      ...I18nSettingsFragment
    }
    talentProfile {
      ...TalentProfileFragment
    }
  }
}
Response
{
  "data": {
    "user": {
      "id": "4",
      "nid": 4,
      "rid": 4,
      "email": "abc123",
      "name": "abc123",
      "permissions": UserPermissions,
      "photoUrl": "xyz789",
      "offer": ContractOfferConnection,
      "timeReport": [TimeReport],
      "contractTimeReport": TimeReportConnection,
      "freelancerProfile": FreelancerProfile,
      "ciphertext": "xyz789",
      "i18NSettings": I18nSettings,
      "talentProfile": TalentProfile
    }
  }
}

userDetails

Description

Retrieve the user details of the used ID

Response

Returns a PiiUser!

Arguments
Name Description
id - ID!

Example

Query
query userDetails($id: ID!) {
  userDetails(id: $id) {
    id
    nid
    rid
    name
    firstName
    lastName
    photoUrl
    publicUrl
    email
    location {
      ...UserLocationFragment
    }
    ciphertext
  }
}
Variables
{"id": 4}
Response
{
  "data": {
    "userDetails": {
      "id": 4,
      "nid": "4",
      "rid": 4,
      "name": "abc123",
      "firstName": "abc123",
      "lastName": "abc123",
      "photoUrl": "abc123",
      "publicUrl": "abc123",
      "email": "xyz789",
      "location": UserLocation,
      "ciphertext": "abc123"
    }
  }
}

userIdsByEmail

Description

List of users by email

Response

Returns a UserIdsByEmailResponse

Arguments
Name Description
email - String!

Example

Query
query userIdsByEmail($email: String!) {
  userIdsByEmail(email: $email) {
    totalCount
    edges {
      ...UserIdsByEmailRecordEdgeFragment
    }
  }
}
Variables
{"email": "xyz789"}
Response
{
  "data": {
    "userIdsByEmail": {
      "totalCount": 987,
      "edges": [UserIdsByEmailRecordEdge]
    }
  }
}
Ontology

ontologyAttributeGroupsForOccupation

Description

Returns the attribute groups associated to the occupation with the given uid. Per each attribute group it includes a maximum of 6 skills nodes corresponding to the narrower ones with highest priority. It also returns the node corresponding to the broader occupations. This is because attribute groups are inherited so clients may want to know if the given attribute group belongs to a broader occupation.

In resume, this endpoint returns a response formed by:

1) The occupation corresponding to the uid passed as parameter.

2) The broader occupations of the given occupation and their broader, and the broader of the broader and so on until no more. These occupations are in a map, with the uid of each as key.

3) The attribute groups required by the occupation and the broader occupations.Per attribute group, a maximum of 6 nodes, with the highest priority, among the narrower nodes of the attribute group. All these required skills are in a map, with the uid of each as a key.

Deprecated elements are not returned and neither the "paths" in which they are included. For example, a skill not deprecated is not returned if the attribute group it belongs is deprecated.

If metadataContext parameter is provided then relevant metadata is loaded and applied: attributes and attribute groups with visibility=false are filtered out from results, priorities are overwritten with the ones in metadata. @param occupationUid identifier of the occupation @param metadataContext context of the metadata to load. If not provided no metadata is loaded or applied. @param metadataCategoryUid UID of the category for metadata path. If not provided then primary category is used. @param metadataSubCategoryUid uid of the subcategory for metadata path. If not provided then primary subcategory is used. @return occupation with the uid passed as parameter, broader occupations and skills required by the occupation

Response

Returns an OccupationAttrGroupsResponse!

Arguments
Name Description
filter - OccupationAttrGroupFilter

Example

Query
query ontologyAttributeGroupsForOccupation($filter: OccupationAttrGroupFilter) {
  ontologyAttributeGroupsForOccupation(filter: $filter) {
    occupation {
      ...OccupationFragment
    }
    broaderOccupations {
      ...BroaderOccupationMapFragment
    }
    attributeGroups {
      ...SkillFragment
    }
    attributes {
      ...AttributeSkillsMapFragment
    }
  }
}
Variables
{"filter": OccupationAttrGroupFilter}
Response
{
  "data": {
    "ontologyAttributeGroupsForOccupation": {
      "occupation": Occupation,
      "broaderOccupations": [BroaderOccupationMap],
      "attributeGroups": [Skill],
      "attributes": [AttributeSkillsMap]
    }
  }
}

ontologyBrowserSkills

Description

Return: list of browser skills paginated with limit and offset

Response

Returns [Skill!]!

Arguments
Name Description
limit - Int!
offset - Int

Example

Query
query ontologyBrowserSkills(
  $limit: Int!,
  $offset: Int
) {
  ontologyBrowserSkills(
    limit: $limit,
    offset: $offset
  ) {
    id
    ontologyId
    type
    entityStatus
    preferredLabel
    createdDateTime
    modifiedDateTime
    definition
    altLabel
    narrower
    narrowerIds
    broader
    broaderIds
    dependsOn
    dependsOnIds
    splitInto
    splitIntoIds
    mergedInto
    mergedIntoId
    replacedBy
    replacedById
    scopeNote
    externalLink
    exactMatch
    exactMatchIds
    closeMatch
    closeMatchIds
    comment
    attributeLevel
    allowMultipleClient
    allowMultipleFreelancer
    allowOther
    clientQuestion
    clientTip
    freelancerQuestion
    freelancerTip
    advancedClient
    client
    freelancer
    requiredClient
    requiredFreelancer
    otherClientLabel
    otherFreelancerLabel
    presentationMode
    priority
    isRequiredBy
    isRequiredByIds
    legacySkillNid
    prettyName
    legacySkillId
  }
}
Variables
{"limit": 123, "offset": 987}
Response
{
  "data": {
    "ontologyBrowserSkills": [
      {
        "id": 4,
        "ontologyId": "abc123",
        "type": ["OCCUPATION"],
        "entityStatus": "ACTIVE",
        "preferredLabel": "abc123",
        "createdDateTime": "abc123",
        "modifiedDateTime": "abc123",
        "definition": "xyz789",
        "altLabel": ["abc123"],
        "narrower": ["xyz789"],
        "narrowerIds": ["4"],
        "broader": ["abc123"],
        "broaderIds": [4],
        "dependsOn": ["xyz789"],
        "dependsOnIds": ["4"],
        "splitInto": ["xyz789"],
        "splitIntoIds": ["4"],
        "mergedInto": "xyz789",
        "mergedIntoId": 4,
        "replacedBy": "xyz789",
        "replacedById": 4,
        "scopeNote": "xyz789",
        "externalLink": ["xyz789"],
        "exactMatch": ["xyz789"],
        "exactMatchIds": ["4"],
        "closeMatch": ["abc123"],
        "closeMatchIds": ["4"],
        "comment": "abc123",
        "attributeLevel": ["abc123"],
        "allowMultipleClient": true,
        "allowMultipleFreelancer": false,
        "allowOther": false,
        "clientQuestion": "abc123",
        "clientTip": "abc123",
        "freelancerQuestion": "abc123",
        "freelancerTip": "abc123",
        "advancedClient": true,
        "client": true,
        "freelancer": false,
        "requiredClient": false,
        "requiredFreelancer": true,
        "otherClientLabel": "abc123",
        "otherFreelancerLabel": "xyz789",
        "presentationMode": "abc123",
        "priority": 987,
        "isRequiredBy": ["xyz789"],
        "isRequiredByIds": ["4"],
        "legacySkillNid": "abc123",
        "prettyName": "abc123",
        "legacySkillId": 4
      }
    ]
  }
}

ontologyCategories

Description

fetch all enabled categories/subcategories/services

Response

Returns [OntologyCategory!]!

Example

Query
query ontologyCategories {
  ontologyCategories {
    id
    preferredLabel
    altLabel
    slug
    ontologyId
    subcategories {
      ...OntologySubcategoryFragment
    }
    services {
      ...OntologyServiceFragment
    }
  }
}
Response
{
  "data": {
    "ontologyCategories": [
      {
        "id": 4,
        "preferredLabel": "xyz789",
        "altLabel": ["abc123"],
        "slug": "xyz789",
        "ontologyId": "xyz789",
        "subcategories": [OntologySubcategory],
        "services": [OntologyService]
      }
    ]
  }
}

ontologyCategorySubcategory

Description

Return: list of category-subcategory pairs occupations for the occupation with the uid sent in the parameter

Response

Returns [CategorySubcategory!]!

Arguments
Name Description
id - ID!

Example

Query
query ontologyCategorySubcategory($id: ID!) {
  ontologyCategorySubcategory(id: $id) {
    category {
      ...OccupationFragment
    }
    subcategory {
      ...OccupationFragment
    }
  }
}
Variables
{"id": 4}
Response
{
  "data": {
    "ontologyCategorySubcategory": [
      {
        "category": Occupation,
        "subcategory": Occupation
      }
    ]
  }
}

ontologyDeliverables

Description

Return: ontology elements of type Deliverables filtered by limit, offset and includeDeprecated

Response

Returns [Deliverable!]

Arguments
Name Description
filter - OntologyDeliverablesFilter!

Example

Query
query ontologyDeliverables($filter: OntologyDeliverablesFilter!) {
  ontologyDeliverables(filter: $filter) {
    id
    ontologyId
    type
    entityStatus
    preferredLabel
    definition
    createdDateTime
    modifiedDateTime
  }
}
Variables
{"filter": OntologyDeliverablesFilter}
Response
{
  "data": {
    "ontologyDeliverables": [
      {
        "id": 4,
        "ontologyId": "abc123",
        "type": ["OCCUPATION"],
        "entityStatus": "ACTIVE",
        "preferredLabel": "xyz789",
        "definition": "abc123",
        "createdDateTime": "abc123",
        "modifiedDateTime": "xyz789"
      }
    ]
  }
}

ontologyElementCategories

Description

Get the list of categories (L1 occupations) that include the provided element in downstream hierarchy

Response

Returns [Occupation!]!

Arguments
Name Description
elementId - ID!

Example

Query
query ontologyElementCategories($elementId: ID!) {
  ontologyElementCategories(elementId: $elementId) {
    id
    ontologyId
    type
    entityStatus
    preferredLabel
    definition
    createdDateTime
    modifiedDateTime
    skills {
      ...SkillFragment
    }
  }
}
Variables
{"elementId": "4"}
Response
{
  "data": {
    "ontologyElementCategories": [
      {
        "id": 4,
        "ontologyId": "abc123",
        "type": ["OCCUPATION"],
        "entityStatus": "ACTIVE",
        "preferredLabel": "abc123",
        "definition": "xyz789",
        "createdDateTime": "xyz789",
        "modifiedDateTime": "abc123",
        "skills": [Skill]
      }
    ]
  }
}

ontologyElementsGraphSearchByIds

Description

Allows search of elements by ids in graph

Return: elements that have provided in id ontology Id, or legacy Uids

Response

Returns [OntologyGraphNode!]!

Arguments
Name Description
ids - [ID!]!
metadataContext - String
metadataFilter - [String!]

Example

Query
query ontologyElementsGraphSearchByIds(
  $ids: [ID!]!,
  $metadataContext: String,
  $metadataFilter: [String!]
) {
  ontologyElementsGraphSearchByIds(
    ids: $ids,
    metadataContext: $metadataContext,
    metadataFilter: $metadataFilter
  ) {
    id
    uid
    label
    types
    status
    properties {
      ...PropertyStringMapFragment
    }
    relationships {
      ...StringListMapFragment
    }
    metadata {
      ...StringMapElementFragment
    }
  }
}
Variables
{
  "ids": ["4"],
  "metadataContext": "xyz789",
  "metadataFilter": ["xyz789"]
}
Response
{
  "data": {
    "ontologyElementsGraphSearchByIds": [
      {
        "id": "4",
        "uid": "4",
        "label": "xyz789",
        "types": ["abc123"],
        "status": "ACTIVE",
        "properties": [PropertyStringMap],
        "relationships": [StringListMap],
        "metadata": [StringMapElement]
      }
    ]
  }
}

ontologyElementsGraphSearchByPrefLabel

Description

Allows search of elements by prefLabel in graph

Return: elements that have provided string in prefLabel, at start, end or in the middle; case insensitive

Response

Returns [OntologyGraphNode!]!

Arguments
Name Description
filter - OntologyElementsSearchByPrefLabelFilter

Example

Query
query ontologyElementsGraphSearchByPrefLabel($filter: OntologyElementsSearchByPrefLabelFilter) {
  ontologyElementsGraphSearchByPrefLabel(filter: $filter) {
    id
    uid
    label
    types
    status
    properties {
      ...PropertyStringMapFragment
    }
    relationships {
      ...StringListMapFragment
    }
    metadata {
      ...StringMapElementFragment
    }
  }
}
Variables
{"filter": OntologyElementsSearchByPrefLabelFilter}
Response
{
  "data": {
    "ontologyElementsGraphSearchByPrefLabel": [
      {
        "id": "4",
        "uid": "4",
        "label": "abc123",
        "types": ["xyz789"],
        "status": "ACTIVE",
        "properties": [PropertyStringMap],
        "relationships": [StringListMap],
        "metadata": [StringMapElement]
      }
    ]
  }
}

ontologyElementsSearchByPrefLabel

Description

Allows search of elements by prefLabel

Return: elements that have provided string in prefLabel, at start, end or in the middle; case insensitive

Response

Returns [OntologyEntity!]!

Arguments
Name Description
filter - OntologyElementsSearchByPrefLabelFilter

Example

Query
query ontologyElementsSearchByPrefLabel($filter: OntologyElementsSearchByPrefLabelFilter) {
  ontologyElementsSearchByPrefLabel(filter: $filter) {
    id
    ontologyId
    type
    entityStatus
    preferredLabel
    definition
    createdDateTime
    modifiedDateTime
  }
}
Variables
{"filter": OntologyElementsSearchByPrefLabelFilter}
Response
{
  "data": {
    "ontologyElementsSearchByPrefLabel": [
      {
        "id": 4,
        "ontologyId": "abc123",
        "type": ["OCCUPATION"],
        "entityStatus": "ACTIVE",
        "preferredLabel": "xyz789",
        "definition": "abc123",
        "createdDateTime": "xyz789",
        "modifiedDateTime": "xyz789"
      }
    ]
  }
}

ontologyEntities

Description

lookup entities by ids

Response

Returns [OntologyEntityResult!]!

Arguments
Name Description
ids - [String!]!

Example

Query
query ontologyEntities($ids: [String!]!) {
  ontologyEntities(ids: $ids) {
    ... on Skill {
      ...SkillFragment
    }
    ... on Occupation {
      ...OccupationFragment
    }
  }
}
Variables
{"ids": ["abc123"]}
Response
{"data": {"ontologyEntities": [Skill]}}

ontologyEntitiesFiltered

Description

lookup entities by pref label and status, currently this field supports only taxonomyLevel=SERVICE E.g supported filtering : ontologyEntityFilter:{preferredLabel_any:"javascript", taxonomyLevel: SERVICE, limit: 5}

Response

Returns an OntologyConnection

Arguments
Name Description
ontologyEntityFilter - OntologyEntityFilter
pagination - Pagination

Example

Query
query ontologyEntitiesFiltered(
  $ontologyEntityFilter: OntologyEntityFilter,
  $pagination: Pagination
) {
  ontologyEntitiesFiltered(
    ontologyEntityFilter: $ontologyEntityFilter,
    pagination: $pagination
  ) {
    totalCount
    edges {
      ...OntologyEntityEdgeFragment
    }
    pageInfo {
      ...PageInfoFragment
    }
  }
}
Variables
{
  "ontologyEntityFilter": OntologyEntityFilter,
  "pagination": Pagination
}
Response
{
  "data": {
    "ontologyEntitiesFiltered": {
      "totalCount": 987,
      "edges": [OntologyEntityEdge],
      "pageInfo": PageInfo
    }
  }
}

ontologyEntity

Description

fetch entity by id

Response

Returns an OntologyEntityResult

Arguments
Name Description
id - ID!

Example

Query
query ontologyEntity($id: ID!) {
  ontologyEntity(id: $id) {
    ... on Skill {
      ...SkillFragment
    }
    ... on Occupation {
      ...OccupationFragment
    }
  }
}
Variables
{"id": "4"}
Response
{"data": {"ontologyEntity": Skill}}

ontologyEntitySearchRecords

Description

search ontology entities by ontoloyIds ontologyId is consistent accross all environments as opposed to UID which is unique per environment example: upwork:AndroidGameDevelopmentEngines

Arguments
Name Description
filter - OntologyEntitySearchFilter!

Example

Query
query ontologyEntitySearchRecords($filter: OntologyEntitySearchFilter!) {
  ontologyEntitySearchRecords(filter: $filter) {
    ontologyEntity {
      ...OntologyEntityFragment
    }
  }
}
Variables
{"filter": OntologyEntitySearchFilter}
Response
{
  "data": {
    "ontologyEntitySearchRecords": [
      {"ontologyEntity": OntologyEntity}
    ]
  }
}

ontologyOccupationCategorySubcategoryGraph

Description

Return a list of graph category-subcategory pairs occupations for the occupation with the uid sent in the parameter

Response

Returns [OntologyRelatedNodes]

Arguments
Name Description
id - ID

Example

Query
query ontologyOccupationCategorySubcategoryGraph($id: ID) {
  ontologyOccupationCategorySubcategoryGraph(id: $id) {
    source {
      ...OntologyGraphNodeFragment
    }
    target {
      ...OntologyGraphNodeFragment
    }
    relationProperties {
      ...PropertyStringMapFragment
    }
  }
}
Variables
{"id": 4}
Response
{
  "data": {
    "ontologyOccupationCategorySubcategoryGraph": [
      {
        "source": OntologyGraphNode,
        "target": OntologyGraphNode,
        "relationProperties": [PropertyStringMap]
      }
    ]
  }
}

ontologyOccupations

Description

Returns ontology elements of type Occupation

Response

Returns [Occupation!]!

Arguments
Name Description
filter - OntologyOccupationFilter!

Example

Query
query ontologyOccupations($filter: OntologyOccupationFilter!) {
  ontologyOccupations(filter: $filter) {
    id
    ontologyId
    type
    entityStatus
    preferredLabel
    definition
    createdDateTime
    modifiedDateTime
    skills {
      ...SkillFragment
    }
  }
}
Variables
{"filter": OntologyOccupationFilter}
Response
{
  "data": {
    "ontologyOccupations": [
      {
        "id": 4,
        "ontologyId": "xyz789",
        "type": ["OCCUPATION"],
        "entityStatus": "ACTIVE",
        "preferredLabel": "abc123",
        "definition": "xyz789",
        "createdDateTime": "xyz789",
        "modifiedDateTime": "abc123",
        "skills": [Skill]
      }
    ]
  }
}

ontologyOccupationsCategoriesServices

Description

Searches occupations categories services by list of category Uids

Return: list of categories and a map of every category and related services

Response

Returns a CategoryServicesResponse

Arguments
Name Description
categoryUids - [ID!]

Example

Query
query ontologyOccupationsCategoriesServices($categoryUids: [ID!]) {
  ontologyOccupationsCategoriesServices(categoryUids: $categoryUids) {
    categories {
      ...OccupationFragment
    }
    categoryServices {
      ...StringMapOccupationFragment
    }
  }
}
Variables
{"categoryUids": ["4"]}
Response
{
  "data": {
    "ontologyOccupationsCategoriesServices": {
      "categories": [Occupation],
      "categoryServices": [StringMapOccupation]
    }
  }
}

ontologyOccupationsCategoriesServicesGraph

Description

Return a list of graph category services occupations for the occupation list with the uids sent in the parameter

Response

Returns [OntologyGraphNode!]

Arguments
Name Description
categoryIds - [ID!]!

Example

Query
query ontologyOccupationsCategoriesServicesGraph($categoryIds: [ID!]!) {
  ontologyOccupationsCategoriesServicesGraph(categoryIds: $categoryIds) {
    id
    uid
    label
    types
    status
    properties {
      ...PropertyStringMapFragment
    }
    relationships {
      ...StringListMapFragment
    }
    metadata {
      ...StringMapElementFragment
    }
  }
}
Variables
{"categoryIds": ["4"]}
Response
{
  "data": {
    "ontologyOccupationsCategoriesServicesGraph": [
      {
        "id": "4",
        "uid": 4,
        "label": "abc123",
        "types": ["xyz789"],
        "status": "ACTIVE",
        "properties": [PropertyStringMap],
        "relationships": [StringListMap],
        "metadata": [StringMapElement]
      }
    ]
  }
}

ontologyOccupationsCategoriesSubcategoriesGraph

Description

Return a list of graph category subcategories occupations

Response

Returns [OntologyGraphNode!]!

Example

Query
query ontologyOccupationsCategoriesSubcategoriesGraph {
  ontologyOccupationsCategoriesSubcategoriesGraph {
    id
    uid
    label
    types
    status
    properties {
      ...PropertyStringMapFragment
    }
    relationships {
      ...StringListMapFragment
    }
    metadata {
      ...StringMapElementFragment
    }
  }
}
Response
{
  "data": {
    "ontologyOccupationsCategoriesSubcategoriesGraph": [
      {
        "id": 4,
        "uid": 4,
        "label": "abc123",
        "types": ["xyz789"],
        "status": "ACTIVE",
        "properties": [PropertyStringMap],
        "relationships": [StringListMap],
        "metadata": [StringMapElement]
      }
    ]
  }
}

ontologyOccupationServices

Description

Return: list of services for a specific occupation

Response

Returns [Occupation!]!

Arguments
Name Description
id - ID!

Example

Query
query ontologyOccupationServices($id: ID!) {
  ontologyOccupationServices(id: $id) {
    id
    ontologyId
    type
    entityStatus
    preferredLabel
    definition
    createdDateTime
    modifiedDateTime
    skills {
      ...SkillFragment
    }
  }
}
Variables
{"id": 4}
Response
{
  "data": {
    "ontologyOccupationServices": [
      {
        "id": "4",
        "ontologyId": "abc123",
        "type": ["OCCUPATION"],
        "entityStatus": "ACTIVE",
        "preferredLabel": "xyz789",
        "definition": "xyz789",
        "createdDateTime": "xyz789",
        "modifiedDateTime": "abc123",
        "skills": [Skill]
      }
    ]
  }
}

ontologyOccupationSkillsCount

Description

Return: number of active attributes with type Skill available in the occupation

Response

Returns an Int!

Arguments
Name Description
id - ID!

Example

Query
query ontologyOccupationSkillsCount($id: ID!) {
  ontologyOccupationSkillsCount(id: $id)
}
Variables
{"id": 4}
Response
{"data": {"ontologyOccupationSkillsCount": 123}}

ontologyPublishedServices

Description

Return: services available for creating specialized profiles. Since all active services are published already

Response

Returns [Occupation!]!

Arguments
Name Description
limit - Int!
offset - Int

Example

Query
query ontologyPublishedServices(
  $limit: Int!,
  $offset: Int
) {
  ontologyPublishedServices(
    limit: $limit,
    offset: $offset
  ) {
    id
    ontologyId
    type
    entityStatus
    preferredLabel
    definition
    createdDateTime
    modifiedDateTime
    skills {
      ...SkillFragment
    }
  }
}
Variables
{"limit": 123, "offset": 123}
Response
{
  "data": {
    "ontologyPublishedServices": [
      {
        "id": 4,
        "ontologyId": "abc123",
        "type": ["OCCUPATION"],
        "entityStatus": "ACTIVE",
        "preferredLabel": "xyz789",
        "definition": "abc123",
        "createdDateTime": "xyz789",
        "modifiedDateTime": "xyz789",
        "skills": [Skill]
      }
    ]
  }
}

ontologySkillNamesByServiceUid

Description

Allows search of skill names by service uid

Return: skill uid and skill pref label

Response

Returns [SkillName!]!

Arguments
Name Description
uid - ID

Example

Query
query ontologySkillNamesByServiceUid($uid: ID) {
  ontologySkillNamesByServiceUid(uid: $uid) {
    id
    preferredLabel
  }
}
Variables
{"uid": "4"}
Response
{
  "data": {
    "ontologySkillNamesByServiceUid": [
      {"id": 4, "preferredLabel": "abc123"}
    ]
  }
}

ontologySkills

Description

Return: list of skills paginated with limit and offset

Response

Returns [Skill!]!

Arguments
Name Description
limit - Int!
offset - Int

Example

Query
query ontologySkills(
  $limit: Int!,
  $offset: Int
) {
  ontologySkills(
    limit: $limit,
    offset: $offset
  ) {
    id
    ontologyId
    type
    entityStatus
    preferredLabel
    createdDateTime
    modifiedDateTime
    definition
    altLabel
    narrower
    narrowerIds
    broader
    broaderIds
    dependsOn
    dependsOnIds
    splitInto
    splitIntoIds
    mergedInto
    mergedIntoId
    replacedBy
    replacedById
    scopeNote
    externalLink
    exactMatch
    exactMatchIds
    closeMatch
    closeMatchIds
    comment
    attributeLevel
    allowMultipleClient
    allowMultipleFreelancer
    allowOther
    clientQuestion
    clientTip
    freelancerQuestion
    freelancerTip
    advancedClient
    client
    freelancer
    requiredClient
    requiredFreelancer
    otherClientLabel
    otherFreelancerLabel
    presentationMode
    priority
    isRequiredBy
    isRequiredByIds
    legacySkillNid
    prettyName
    legacySkillId
  }
}
Variables
{"limit": 987, "offset": 987}
Response
{
  "data": {
    "ontologySkills": [
      {
        "id": 4,
        "ontologyId": "abc123",
        "type": ["OCCUPATION"],
        "entityStatus": "ACTIVE",
        "preferredLabel": "abc123",
        "createdDateTime": "xyz789",
        "modifiedDateTime": "xyz789",
        "definition": "xyz789",
        "altLabel": ["abc123"],
        "narrower": ["xyz789"],
        "narrowerIds": [4],
        "broader": ["abc123"],
        "broaderIds": [4],
        "dependsOn": ["xyz789"],
        "dependsOnIds": ["4"],
        "splitInto": ["xyz789"],
        "splitIntoIds": [4],
        "mergedInto": "xyz789",
        "mergedIntoId": "4",
        "replacedBy": "xyz789",
        "replacedById": "4",
        "scopeNote": "xyz789",
        "externalLink": ["xyz789"],
        "exactMatch": ["abc123"],
        "exactMatchIds": [4],
        "closeMatch": ["abc123"],
        "closeMatchIds": [4],
        "comment": "abc123",
        "attributeLevel": ["abc123"],
        "allowMultipleClient": true,
        "allowMultipleFreelancer": false,
        "allowOther": true,
        "clientQuestion": "xyz789",
        "clientTip": "xyz789",
        "freelancerQuestion": "abc123",
        "freelancerTip": "xyz789",
        "advancedClient": true,
        "client": false,
        "freelancer": true,
        "requiredClient": false,
        "requiredFreelancer": false,
        "otherClientLabel": "abc123",
        "otherFreelancerLabel": "xyz789",
        "presentationMode": "abc123",
        "priority": 123,
        "isRequiredBy": ["xyz789"],
        "isRequiredByIds": [4],
        "legacySkillNid": "abc123",
        "prettyName": "xyz789",
        "legacySkillId": "4"
      }
    ]
  }
}

ontologySkillsByAttributeGroup

Description

Return: list of element/skills pair by attribute group

Response

Returns [ElementSkillMap!]!

Arguments
Name Description
filter - AttrGroupFilter!

Example

Query
query ontologySkillsByAttributeGroup($filter: AttrGroupFilter!) {
  ontologySkillsByAttributeGroup(filter: $filter) {
    element
    skill {
      ...SkillFragment
    }
  }
}
Variables
{"filter": AttrGroupFilter}
Response
{
  "data": {
    "ontologySkillsByAttributeGroup": [
      {
        "element": "xyz789",
        "skill": Skill
      }
    ]
  }
}

ontologySkillsRecords

Description

fetch all enabled skills

Response

Returns [OntologySkill!]!

Arguments
Name Description
filter - OntologySkillsFilter
pagination - Pagination

Example

Query
query ontologySkillsRecords(
  $filter: OntologySkillsFilter,
  $pagination: Pagination
) {
  ontologySkillsRecords(
    filter: $filter,
    pagination: $pagination
  ) {
    id
    preferredLabel
    ontologyId
  }
}
Variables
{
  "filter": OntologySkillsFilter,
  "pagination": Pagination
}
Response
{
  "data": {
    "ontologySkillsRecords": [
      {
        "id": "4",
        "preferredLabel": "xyz789",
        "ontologyId": "abc123"
      }
    ]
  }
}

ontologyVisitorCategories

Description

fetch all enabled visitor categories/subcategories/services

Response

Returns [OntologyCategory!]!

Example

Query
query ontologyVisitorCategories {
  ontologyVisitorCategories {
    id
    preferredLabel
    altLabel
    slug
    ontologyId
    subcategories {
      ...OntologySubcategoryFragment
    }
    services {
      ...OntologyServiceFragment
    }
  }
}
Response
{
  "data": {
    "ontologyVisitorCategories": [
      {
        "id": "4",
        "preferredLabel": "xyz789",
        "altLabel": ["xyz789"],
        "slug": "xyz789",
        "ontologyId": "abc123",
        "subcategories": [OntologySubcategory],
        "services": [OntologyService]
      }
    ]
  }
}

freelancerProfileSearchRecords

Arguments
Name Description
searchFilter - FreelancerProfileSearchFilter!
pagination - Pagination!

Example

Query
query freelancerProfileSearchRecords(
  $searchFilter: FreelancerProfileSearchFilter!,
  $pagination: Pagination!
) {
  freelancerProfileSearchRecords(
    searchFilter: $searchFilter,
    pagination: $pagination
  ) {
    edges {
      ...FreelancerProfilesSearchResultEdgeFragment
    }
    pageInfo {
      ...PageInfoFragment
    }
    totalCount
  }
}
Variables
{
  "searchFilter": FreelancerProfileSearchFilter,
  "pagination": Pagination
}
Response
{
  "data": {
    "freelancerProfileSearchRecords": {
      "edges": [FreelancerProfilesSearchResultEdge],
      "pageInfo": PageInfo,
      "totalCount": 987
    }
  }
}
Metadata

countries

Description

List of countries. Currently no filtering is available

Response

Returns [Country!]!

Example

Query
query countries {
  countries {
    id
    name
    twoLetterAbbreviation
    threeLetterAbbreviation
    region
    phoneCode
    relatedRegion {
      ...RegionFragment
    }
    relatedSubRegion {
      ...RegionFragment
    }
    active
    registrationAllowed
  }
}
Response
{
  "data": {
    "countries": [
      {
        "id": "4",
        "name": "xyz789",
        "twoLetterAbbreviation": "abc123",
        "threeLetterAbbreviation": "abc123",
        "region": "EU",
        "phoneCode": "abc123",
        "relatedRegion": Region,
        "relatedSubRegion": Region,
        "active": false,
        "registrationAllowed": false
      }
    ]
  }
}

languages

Response

Returns [Language!]!

Example

Query
query languages {
  languages {
    iso639Code
    active
    englishName
  }
}
Response
{
  "data": {
    "languages": [
      {
        "iso639Code": "xyz789",
        "active": true,
        "englishName": "xyz789"
      }
    ]
  }
}

reasons

Description

Reasons for some actions. Examples - declining invitation, ending contract, withdrawing offer

Response

Returns [ReasonsMetadata!]!

Arguments
Name Description
reasonType - ReasonType!
all - Boolean

Example

Query
query reasons(
  $reasonType: ReasonType!,
  $all: Boolean
) {
  reasons(
    reasonType: $reasonType,
    all: $all
  ) {
    id
    reason
    alias
  }
}
Variables
{"reasonType": "PROPOSAL_DECLINE", "all": true}
Response
{
  "data": {
    "reasons": [
      {
        "id": "4",
        "reason": "xyz789",
        "alias": "abc123"
      }
    ]
  }
}

regions

Response

Returns [Region!]

Example

Query
query regions {
  regions {
    id
    name
    parentRegion {
      ...RegionFragment
    }
  }
}
Response
{
  "data": {
    "regions": [
      {
        "id": "4",
        "name": "xyz789",
        "parentRegion": Region
      }
    ]
  }
}

requestMetadata

Description

Information about request - whether it is an internal requests, in sudo mode, etc

Response

Returns a RequestMetadata!

Example

Query
query requestMetadata {
  requestMetadata {
    sudo
    internal
  }
}
Response
{"data": {"requestMetadata": {"sudo": false, "internal": false}}}

timeZones

Description

List of all availabe time zones

Response

Returns [TimeZoneRecord!]!

Example

Query
query timeZones {
  timeZones {
    timeZoneName
    timeZoneDescription
  }
}
Response
{
  "data": {
    "timeZones": [
      {
        "timeZoneName": "abc123",
        "timeZoneDescription": "xyz789"
      }
    ]
  }
}

visitor

Response

Returns a Visitor

Example

Query
query visitor {
  visitor {
    i18n {
      ...VisitorI18NFragment
    }
    segment {
      ...VisitorSegmentFragment
    }
  }
}
Response
{
  "data": {
    "visitor": {
      "i18n": VisitorI18N,
      "segment": VisitorSegment
    }
  }
}
Other

accountingEntity

Description

Get the Accounting Entity of the current user from their organization uid

Response

Returns an AccountingEntity!

Example

Query
query accountingEntity {
  accountingEntity {
    id
  }
}
Response
{"data": {"accountingEntity": {"id": "4"}}}

backofficeOffer

Description

Offer by ID is taken from modernized offersContractsQuery service

Response

Returns a ModernizedOffer

Arguments
Name Description
id - ID!

Example

Query
query backofficeOffer($id: ID!) {
  backofficeOffer(id: $id) {
    id
    kind
    offeror
    clientUserId
    clientTeamId
    clientOrgId
    vendorUserId
    vendorTeamId
    vendorOrgId
    actors {
      ...ActorFragment
    }
    metadata {
      ...MetadataFragment
    }
    expirationDateTime
    title
    description
    attachments
    contractStartDateTime
    contractEndDateTime
    hourlyRateTerms {
      ...HourlyTermsFragment
    }
    stipendTerms {
      ...StipendTermsFragment
    }
    milestoneTerms {
      ...MilestoneTermsFragment
    }
    deliveryModel
    state
    staffingManagerId
    contractId
    agencyRootCompanyId
    instanceId
    client {
      ...GenericOrganizationFragment
    }
    clientCompany {
      ...PublicCompanyInfoFragment
    }
    createdDateTime
  }
}
Variables
{"id": "4"}
Response
{
  "data": {
    "backofficeOffer": {
      "id": 4,
      "kind": "HourlyPack",
      "offeror": "Client",
      "clientUserId": "4",
      "clientTeamId": "4",
      "clientOrgId": 4,
      "vendorUserId": "4",
      "vendorTeamId": "4",
      "vendorOrgId": "4",
      "actors": [Actor],
      "metadata": Metadata,
      "expirationDateTime": "xyz789",
      "title": "xyz789",
      "description": "abc123",
      "attachments": ["4"],
      "contractStartDateTime": "abc123",
      "contractEndDateTime": "xyz789",
      "hourlyRateTerms": HourlyTerms,
      "stipendTerms": StipendTerms,
      "milestoneTerms": MilestoneTerms,
      "deliveryModel": "TalentMarketplace",
      "state": "Submitted",
      "staffingManagerId": "4",
      "contractId": 4,
      "agencyRootCompanyId": 4,
      "instanceId": 4,
      "client": GenericOrganization,
      "clientCompany": PublicCompanyInfo,
      "createdDateTime": "xyz789"
    }
  }
}

contractRoom

Description

Returns the interview room associated with the given contractId

Response

Returns a Room

Arguments
Name Description
contractId - ID!

Example

Query
query contractRoom($contractId: ID!) {
  contractRoom(contractId: $contractId) {
    id
    roomName
    organization {
      ...CurrentOrganizationFragment
    }
    creator {
      ...RoomUserFragment
    }
    createdAtDateTime
    public
    topic
    owner {
      ...RoomUserFragment
    }
    numUnread
    roomFavoriteDateTime
    favorite
    numUnreadMentions
    roomUsers {
      ...RoomUserFragment
    }
    numUsers
    joinDateTime
    lastVisitedDateTime
    lastReadDateTime
    roomType
    readOnlyDateTime
    readOnly
    blockDateTime
    blockedBy {
      ...RoomUserFragment
    }
    hidden
    muted
    contractId
    contract {
      ...ContractFragment
    }
    vendorProposal {
      ...VendorProposalFragment
    }
    roomNote
    roomNotePresent
    offerIds
    recruiters {
      ...GenericUserFragment
    }
    latestStory {
      ...RoomStoryFragment
    }
    story {
      ...RoomStoryFragment
    }
    stories {
      ...RoomStoryConnectionFragment
    }
    latestStoryPreRendered {
      ...RoomStoryFragment
    }
  }
}
Variables
{"contractId": "4"}
Response
{
  "data": {
    "contractRoom": {
      "id": 4,
      "roomName": "xyz789",
      "organization": CurrentOrganization,
      "creator": RoomUser,
      "createdAtDateTime": "abc123",
      "public": false,
      "topic": "xyz789",
      "owner": RoomUser,
      "numUnread": 123,
      "roomFavoriteDateTime": "xyz789",
      "favorite": false,
      "numUnreadMentions": 123,
      "roomUsers": [RoomUser],
      "numUsers": 123,
      "joinDateTime": "xyz789",
      "lastVisitedDateTime": "xyz789",
      "lastReadDateTime": "abc123",
      "roomType": "ONE_ON_ONE",
      "readOnlyDateTime": "xyz789",
      "readOnly": false,
      "blockDateTime": "abc123",
      "blockedBy": RoomUser,
      "hidden": true,
      "muted": false,
      "contractId": 4,
      "contract": Contract,
      "vendorProposal": VendorProposal,
      "roomNote": "xyz789",
      "roomNotePresent": false,
      "offerIds": ["4"],
      "recruiters": [GenericUser],
      "latestStory": RoomStory,
      "story": RoomStory,
      "stories": RoomStoryConnection,
      "latestStoryPreRendered": RoomStory
    }
  }
}

offerRoom

Description

Returns room associated with the given offerId

Response

Returns a Room

Arguments
Name Description
offerId - ID!

Example

Query
query offerRoom($offerId: ID!) {
  offerRoom(offerId: $offerId) {
    id
    roomName
    organization {
      ...CurrentOrganizationFragment
    }
    creator {
      ...RoomUserFragment
    }
    createdAtDateTime
    public
    topic
    owner {
      ...RoomUserFragment
    }
    numUnread
    roomFavoriteDateTime
    favorite
    numUnreadMentions
    roomUsers {
      ...RoomUserFragment
    }
    numUsers
    joinDateTime
    lastVisitedDateTime
    lastReadDateTime
    roomType
    readOnlyDateTime
    readOnly
    blockDateTime
    blockedBy {
      ...RoomUserFragment
    }
    hidden
    muted
    contractId
    contract {
      ...ContractFragment
    }
    vendorProposal {
      ...VendorProposalFragment
    }
    roomNote
    roomNotePresent
    offerIds
    recruiters {
      ...GenericUserFragment
    }
    latestStory {
      ...RoomStoryFragment
    }
    story {
      ...RoomStoryFragment
    }
    stories {
      ...RoomStoryConnectionFragment
    }
    latestStoryPreRendered {
      ...RoomStoryFragment
    }
  }
}
Variables
{"offerId": "4"}
Response
{
  "data": {
    "offerRoom": {
      "id": "4",
      "roomName": "abc123",
      "organization": CurrentOrganization,
      "creator": RoomUser,
      "createdAtDateTime": "abc123",
      "public": false,
      "topic": "xyz789",
      "owner": RoomUser,
      "numUnread": 987,
      "roomFavoriteDateTime": "xyz789",
      "favorite": true,
      "numUnreadMentions": 123,
      "roomUsers": [RoomUser],
      "numUsers": 987,
      "joinDateTime": "xyz789",
      "lastVisitedDateTime": "abc123",
      "lastReadDateTime": "abc123",
      "roomType": "ONE_ON_ONE",
      "readOnlyDateTime": "abc123",
      "readOnly": false,
      "blockDateTime": "abc123",
      "blockedBy": RoomUser,
      "hidden": true,
      "muted": false,
      "contractId": 4,
      "contract": Contract,
      "vendorProposal": VendorProposal,
      "roomNote": "xyz789",
      "roomNotePresent": false,
      "offerIds": ["4"],
      "recruiters": [GenericUser],
      "latestStory": RoomStory,
      "story": RoomStory,
      "stories": RoomStoryConnection,
      "latestStoryPreRendered": RoomStory
    }
  }
}

offersByAttributes

Description

Get modernized offers by search for multiple attributes ids. filter - contains data for searching

Response

Returns a ModernizedContractOfferList

Arguments
Name Description
filter - SearchOffersByAttributesInput!

Example

Query
query offersByAttributes($filter: SearchOffersByAttributesInput!) {
  offersByAttributes(filter: $filter) {
    offers {
      ...ModernizedContractOfferFragment
    }
  }
}
Variables
{"filter": SearchOffersByAttributesInput}
Response
{
  "data": {
    "offersByAttributes": {
      "offers": [ModernizedContractOffer]
    }
  }
}

oneOnOneRoom

Description

Returns 1on1 room between the current user and passed user and organization id

Response

Returns a Room

Arguments
Name Description
userId - ID!
organizationId - ID!

Example

Query
query oneOnOneRoom(
  $userId: ID!,
  $organizationId: ID!
) {
  oneOnOneRoom(
    userId: $userId,
    organizationId: $organizationId
  ) {
    id
    roomName
    organization {
      ...CurrentOrganizationFragment
    }
    creator {
      ...RoomUserFragment
    }
    createdAtDateTime
    public
    topic
    owner {
      ...RoomUserFragment
    }
    numUnread
    roomFavoriteDateTime
    favorite
    numUnreadMentions
    roomUsers {
      ...RoomUserFragment
    }
    numUsers
    joinDateTime
    lastVisitedDateTime
    lastReadDateTime
    roomType
    readOnlyDateTime
    readOnly
    blockDateTime
    blockedBy {
      ...RoomUserFragment
    }
    hidden
    muted
    contractId
    contract {
      ...ContractFragment
    }
    vendorProposal {
      ...VendorProposalFragment
    }
    roomNote
    roomNotePresent
    offerIds
    recruiters {
      ...GenericUserFragment
    }
    latestStory {
      ...RoomStoryFragment
    }
    story {
      ...RoomStoryFragment
    }
    stories {
      ...RoomStoryConnectionFragment
    }
    latestStoryPreRendered {
      ...RoomStoryFragment
    }
  }
}
Variables
{
  "userId": "4",
  "organizationId": "4"
}
Response
{
  "data": {
    "oneOnOneRoom": {
      "id": "4",
      "roomName": "xyz789",
      "organization": CurrentOrganization,
      "creator": RoomUser,
      "createdAtDateTime": "abc123",
      "public": true,
      "topic": "abc123",
      "owner": RoomUser,
      "numUnread": 123,
      "roomFavoriteDateTime": "xyz789",
      "favorite": true,
      "numUnreadMentions": 987,
      "roomUsers": [RoomUser],
      "numUsers": 987,
      "joinDateTime": "abc123",
      "lastVisitedDateTime": "xyz789",
      "lastReadDateTime": "xyz789",
      "roomType": "ONE_ON_ONE",
      "readOnlyDateTime": "abc123",
      "readOnly": true,
      "blockDateTime": "xyz789",
      "blockedBy": RoomUser,
      "hidden": true,
      "muted": false,
      "contractId": "4",
      "contract": Contract,
      "vendorProposal": VendorProposal,
      "roomNote": "abc123",
      "roomNotePresent": true,
      "offerIds": ["4"],
      "recruiters": [GenericUser],
      "latestStory": RoomStory,
      "story": RoomStory,
      "stories": RoomStoryConnection,
      "latestStoryPreRendered": RoomStory
    }
  }
}

proposalRoom

Description

Returns room associated with a vendor proposal

Response

Returns a Room!

Arguments
Name Description
vendorProposalId - ID!

Example

Query
query proposalRoom($vendorProposalId: ID!) {
  proposalRoom(vendorProposalId: $vendorProposalId) {
    id
    roomName
    organization {
      ...CurrentOrganizationFragment
    }
    creator {
      ...RoomUserFragment
    }
    createdAtDateTime
    public
    topic
    owner {
      ...RoomUserFragment
    }
    numUnread
    roomFavoriteDateTime
    favorite
    numUnreadMentions
    roomUsers {
      ...RoomUserFragment
    }
    numUsers
    joinDateTime
    lastVisitedDateTime
    lastReadDateTime
    roomType
    readOnlyDateTime
    readOnly
    blockDateTime
    blockedBy {
      ...RoomUserFragment
    }
    hidden
    muted
    contractId
    contract {
      ...ContractFragment
    }
    vendorProposal {
      ...VendorProposalFragment
    }
    roomNote
    roomNotePresent
    offerIds
    recruiters {
      ...GenericUserFragment
    }
    latestStory {
      ...RoomStoryFragment
    }
    story {
      ...RoomStoryFragment
    }
    stories {
      ...RoomStoryConnectionFragment
    }
    latestStoryPreRendered {
      ...RoomStoryFragment
    }
  }
}
Variables
{"vendorProposalId": "4"}
Response
{
  "data": {
    "proposalRoom": {
      "id": "4",
      "roomName": "abc123",
      "organization": CurrentOrganization,
      "creator": RoomUser,
      "createdAtDateTime": "xyz789",
      "public": true,
      "topic": "xyz789",
      "owner": RoomUser,
      "numUnread": 987,
      "roomFavoriteDateTime": "abc123",
      "favorite": false,
      "numUnreadMentions": 123,
      "roomUsers": [RoomUser],
      "numUsers": 123,
      "joinDateTime": "abc123",
      "lastVisitedDateTime": "xyz789",
      "lastReadDateTime": "abc123",
      "roomType": "ONE_ON_ONE",
      "readOnlyDateTime": "abc123",
      "readOnly": true,
      "blockDateTime": "xyz789",
      "blockedBy": RoomUser,
      "hidden": true,
      "muted": true,
      "contractId": 4,
      "contract": Contract,
      "vendorProposal": VendorProposal,
      "roomNote": "abc123",
      "roomNotePresent": true,
      "offerIds": [4],
      "recruiters": [GenericUser],
      "latestStory": RoomStory,
      "story": RoomStory,
      "stories": RoomStoryConnection,
      "latestStoryPreRendered": RoomStory
    }
  }
}

publicRooms

Description

Get public rooms inside an organization

Response

Returns a RoomConnection!

Arguments
Name Description
pagination - Pagination

Example

Query
query publicRooms($pagination: Pagination) {
  publicRooms(pagination: $pagination) {
    totalCount
    edges {
      ...RoomEdgeFragment
    }
    pageInfo {
      ...PageInfoFragment
    }
  }
}
Variables
{"pagination": Pagination}
Response
{
  "data": {
    "publicRooms": {
      "totalCount": 987,
      "edges": [RoomEdge],
      "pageInfo": PageInfo
    }
  }
}

room

Description

Details of a room

Response

Returns a Room!

Arguments
Name Description
id - ID!

Example

Query
query room($id: ID!) {
  room(id: $id) {
    id
    roomName
    organization {
      ...CurrentOrganizationFragment
    }
    creator {
      ...RoomUserFragment
    }
    createdAtDateTime
    public
    topic
    owner {
      ...RoomUserFragment
    }
    numUnread
    roomFavoriteDateTime
    favorite
    numUnreadMentions
    roomUsers {
      ...RoomUserFragment
    }
    numUsers
    joinDateTime
    lastVisitedDateTime
    lastReadDateTime
    roomType
    readOnlyDateTime
    readOnly
    blockDateTime
    blockedBy {
      ...RoomUserFragment
    }
    hidden
    muted
    contractId
    contract {
      ...ContractFragment
    }
    vendorProposal {
      ...VendorProposalFragment
    }
    roomNote
    roomNotePresent
    offerIds
    recruiters {
      ...GenericUserFragment
    }
    latestStory {
      ...RoomStoryFragment
    }
    story {
      ...RoomStoryFragment
    }
    stories {
      ...RoomStoryConnectionFragment
    }
    latestStoryPreRendered {
      ...RoomStoryFragment
    }
  }
}
Variables
{"id": "4"}
Response
{
  "data": {
    "room": {
      "id": 4,
      "roomName": "abc123",
      "organization": CurrentOrganization,
      "creator": RoomUser,
      "createdAtDateTime": "abc123",
      "public": true,
      "topic": "abc123",
      "owner": RoomUser,
      "numUnread": 987,
      "roomFavoriteDateTime": "xyz789",
      "favorite": true,
      "numUnreadMentions": 987,
      "roomUsers": [RoomUser],
      "numUsers": 987,
      "joinDateTime": "xyz789",
      "lastVisitedDateTime": "abc123",
      "lastReadDateTime": "xyz789",
      "roomType": "ONE_ON_ONE",
      "readOnlyDateTime": "abc123",
      "readOnly": true,
      "blockDateTime": "abc123",
      "blockedBy": RoomUser,
      "hidden": true,
      "muted": false,
      "contractId": 4,
      "contract": Contract,
      "vendorProposal": VendorProposal,
      "roomNote": "abc123",
      "roomNotePresent": false,
      "offerIds": ["4"],
      "recruiters": [GenericUser],
      "latestStory": RoomStory,
      "story": RoomStory,
      "stories": RoomStoryConnection,
      "latestStoryPreRendered": RoomStory
    }
  }
}

roomList

Description

List of rooms based on the given filter condition

Response

Returns a RoomConnection!

Arguments
Name Description