Gets the rooms for the current user and organization

GET  /api/messages/v3/{company_id}/rooms.{format} 

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

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

• REST documentation
• GraphQL documentation

Fields:

Gets a specific room information

GET  /api/messages/v3/{company_user_id}/rooms/{room_id}.{format} 

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

{"roomId": 4}

• REST documentation
• GraphQL documentation

Fields:

Gets messages/stories from a specific room

GET  /api/messages/v3/{company_user_id}/rooms/{room_id}/stories.{format} 

query RoomStories($roomId: ID!) {
  roomStories(filter: {roomId_eq: $roomId}) {
    totalCount
    edges {
      node {
        id
        message
      }
    }
  }
}

{"roomId": "4"}

• REST documentation
• GraphQL documentation

Fields:

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

GET  /api/messages/v3/{company_user_id}/rooms/offers/{offer_id}.{format} 

query offerRoom($offerId: ID!) {
  offerRoom(id: $offerId) {
    id
    roomName
  }
}

{"offerId": "4"}

• REST documentation
• GraphQL documentation

Fields:

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

GET  /api/messages/v3/{company_user_id}/rooms/applications/{application_id}.{format} 

query proposalRoom($vendorProposalId: ID!) {
  proposalRoom(id: $vendorProposalId) {
    id
    roomName
  }
}

{"vendorProposalId": "4"}

• REST documentation
• GraphQL documentation

Fields:

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

GET  /api/messages/v3/{company_user_id}/rooms/contracts/{contract_id}.{format} 

query contractRoom($contractId: ID!) {
  contractRoom(id: $contractId) {
    id
    roomName
  }
}

{"contractId": 4}

• REST documentation
• GraphQL documentation

Fields:

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

POST  /api/messages/v3/{company_user_id}/rooms.{format} 

mutation createRoomV2($input: RoomCreateInputV2!) {
  createRoomV2(
    input: $input
  ) {
    id
    roomName
  }
}

{
  "input": {
    "roomName": "abc123",
    "topic": "abc123",
    "roomType": "GROUP",
    "users": [
      {"userId": "112233445566778899", "organizationId": "112233445566778899"}
    ]
  }
}

• REST documentation
• GraphQL documentation

Adds a new story to the given room

POST  /api/messages/v3/{company_user_id}/rooms/{room_id}/stories.{format} 

mutation createRoomStoryV2($input: RoomStoryCreateInputV2!) {
  createRoomStoryV2(input: $input) {
    id
    room {
      ...RoomFragment
    }
    createdDateTime
    updatedDateTime
    user {
      ...GenericUserFragment
    }
    message
    organization {
      ...GenericOrganizationFragment
    }
    roomStoryNote {
      ...RoomStoryNoteFragment
    }
  }
}

{"input": {"roomId": "4", "message": "xyz789"}}

• REST documentation
• GraphQL documentation

Adds a new story to the list of the given rooms

POST  /api/messages/v3/{company_user_id}/stories/batch.{format} 

Same as sending a single message, but multiple mutations in one request

• REST documentation
• GraphQL documentation

Updates a room settings

PUT  /api/messages/v3/{company_user_id}/rooms/{room_id}/users/{user_id}.{format} 

mutation updateRoom($roomId: ID!, $topic: String!) {
  updateRoom(input: {roomId: $roomId, topic: $topic}) {
    id
    roomName
  }
}

{"roomId": 4, "topic": "abc123"}

• REST documentation
• GraphQL documentation

Updates the metadata of an existing room and archives it

PUT  /api/messages/v3/{company_user_id}/rooms/{room_id}.{format} 

mutation archiveRoom($roomId: ID!) {
  archiveRoom(roomId: $roomId) {
    id
    roomName
  }
}

{"roomId": 4}

• REST documentation
• GraphQL documentation

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

GET  /api/hr/v2/engagements
GET /api/hr/v2/engagements.{format} 

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

• REST documentation
• GraphQL documentation

This call retrieves details about a specific engagement.

GET  /api/hr/v2/engagements/{engagement_reference}.{format} 

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

{"id": 4}

• REST documentation
• GraphQL documentation

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

POST  /api/hr/v2/teams/{team_reference}/adjustments.{format} 

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

{
  "contractId": 4,
  "amount": 123.45,
  "comment": "xyz789",
  "notes": "xyz789",
  "allowSubsequent": false
}

• REST documentation
• GraphQL documentation

Fields:

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

GET  /api/profiles/v2/search/providers.{format} 

{
  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
              }
            }
          }
        }
      }
    }
  }
}

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

• REST documentation
• GraphQL documentation

Fields:

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

GET  /api/profiles/v1/providers/{profile_key}/brief.{format} 

query getFreelancerProfile($profileKey: String!) {
  freelancerProfileByProfileKey(profileKey: $profileKey) {
    aggregates {
      ...FreelancerProfileAggregatesFragment
    }
    personalData {
      ...FreelancerProfilePersonalDataFragment
    }
  }
}

{"profileKey": "abc123"}

• REST documentation
• GraphQL documentation

Fields:

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}).

GET  /api/profiles/v1/providers/{profile_key}.{format} 

query talentProfileByProfileKey($profileKey: String!) {
  talentProfileByProfileKey(profileKey: $profileKey) {
    personId
    identity {
      ...TalentProfileIdentityFragment
    }
    personalData {
      ...TalentProfilePersonalDataFragment
    }
    preferences {
      ...TalentProfileUserPreferencesFragment
    }
    settings {
      ...TalentProfileSettingsFragment
    }
    personAvailability {
      ...TalentPersonAvailabilityFragment
    }
    projectList {
      ...TalentProjectListFragment
    }
    communityCertificates {
      ...TalentProfileCommunityCertificateFragment
    }
    profileCompleteness {
      ...TalentProfileCompletenessSummaryFragment
    }
    otherExperiences {
      ...TalentProfileOtherExperienceFragment
    }
    educationRecords {
      ...TalentEducationRecordFragment
    }
    employmentRecords {
      ...TalentProfileEmploymentRecordFragment
    }
    skills {
      ...TalentProfilePersonSkillFragment
    }
    jobCategories {
      ...TalentJobCategoryGroupFragment
    }
    profileAggregates {
      ...TalentProfileAggregateFragment
    }
    specializedProfiles {
      ...TalentSpecializedProfileFragment
    }
    specializedProfilesSkills {
      ...TalentSpecializedProfileSkillFragment
    }
    specializedProfilesProjects {
      ...TalentSpecializedProfilesProjectFragment
    }
  }
}

{"profileKey": "abc123"}

• REST documentation
• GraphQL documentation

Fields:

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.

GET  /api/hr/v2/companies.{format} 

query companies($userId: ID!) {
  companies(userId: $userId) {
    company {
      private {
        id
        companyName
        paymentVerification {
          status
        }
      }
    }
  }
}

{"userId": 4}

• REST documentation
• GraphQL documentation

Fields:

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.

GET  /api/hr/v2/companies/{company_reference}.{format} 

query getCompanyDetails($companyId: ID!) {
  company(id: $id) {
    private {
      id
      companyName
      paymentVerification {
        status
      }
    }
  }
}

{"id": "4"}

• REST documentation
• GraphQL documentation

Fields:

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

GET  /api/hr/v2/teams.{format} 

{
  organization {
    childOrganization {
      id
      company {
        name
      }
      parentOrganization {
        id
        company {
          name
        }
      }
    }
  }
}

• REST documentation
• GraphQL documentation

Fields:

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

GET  /api/hr/v2/teams/{team_reference}/users.{format} 

query getChildOrganizationStaff($childOrganizationId: ID!) {
  organization {
    childOrganization(id: $childOrganizationId) {
      staffs {
        edges {
          node {
            user {
              id
              name
              publicUrl
            }
            staffType
            activationStatus
          }
        }
      }
    }
  }
}

{"childOrganizationId": "yourChildOrganizationIdHere"}

• REST documentation
• GraphQL documentation

Fields:

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.

GET  /api/team/v3/workdiaries/companies/{company_id}/{date}.{format} 

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

{"companyId": 4, "date": "abc123"}

• REST documentation
• GraphQL documentation

Fields:

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

GET  /api/team/v3/workdiaries/contracts/{contract_id}/{date}.{format} 

{
  workDiaryContract(
    workDiaryContractInput: {
      contractId: $contractId,
      date: $date,
      offsetInSeconds: offsetInSeconds,
      useLegacy: useLegacy
    }
  ) {
    workDiaryMetadata {
      user {
        id
        name
      }
      timezoneOffset
      archivingDateTime
    }
    workDiaryTimeCells {
      cellDateTime {
        rawValue
        displayValue
      }
      overtime
      activityLevel
      memo
    }
  }
}

{"contractId": "4", "date": "abc123", "offsetInSeconds": 987, "useLegacy": true}

• REST documentation
• GraphQL documentation

Fields:

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

PUT  /api/hr/v3/fp/submissions/{submission_id}/approve.{format} 

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

{
  "milestoneId": "4",
  "paidAmount": "xyz789",
  "bonusAmount": "abc123",
  "paymentComment": "abc123",
  "underpaymentReason": "xyz789",
  "noteToContractor": "abc123"
}

• REST documentation
• GraphQL documentation

Fields:

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.

PUT  /api/hr/v3/fp/submissions/{submission_id}/reject.{format} 

mutation rejectSubmittedMilestone($milestoneId: String, $noteToContractor: String) {
  rejectSubmittedMilestone(
    input: { id: $milestoneId, noteToContractor: $noteToContractor }
  ) {
    id
  }
}

{"milestoneId": "4", "noteToContractor": "abc123"}

• REST documentation
• GraphQL documentation

Fields:

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

POST  /api/hr/v3/fp/milestones.{format} 

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

{
  "offerId": 4,
  "contractId": 4,
  "description": "abc123",
  "instruction": "abc123",
  "depositAmount": "xyz789",
  "dueDate": "xyz789",
  "attachmentIds": ["4"]
}

• REST documentation
• GraphQL documentation

Fields:

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

PUT  /api/hr/v3/fp/milestones/{milestone_id}.{format} 

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

{
  "id": 4,
  "description": "xyz789",
  "instructions": "abc123",
  "depositAmount": "xyz789",
  "dueDate": "xyz789",
  "attachments": ["4"],
  "message": "abc123",
  "sequenceId": 987
}

• REST documentation
• GraphQL documentation

Fields:

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

PUT  /api/hr/v3/fp/milestones/{milestone_id}/activate.{format} 

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

{"id": "4", "message": "xyz789"}

• REST documentation
• GraphQL documentation

Fields:

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

PUT  /api/hr/v3/fp/milestones/{milestone_id}/approve.{format} 

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

{
  "id": "4",
  "paidAmount": "xyz789",
  "bonusAmount": "abc123",
  "paymentComment": "abc123",
  "underpaymentReason": "xyz789",
  "noteToContractor": "abc123"
}

• REST documentation
• GraphQL documentation

Fields:

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

DELETE  /api/hr/v3/fp/milestones/{milestone_id}.{format} 

mutation deleteMilestone($id: ID!) {
  deleteMilestone(input: {id: $id})
}

{"id": "4"}

• REST documentation
• GraphQL documentation

Fields:

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.

GET  /api/otask/v1/tasks/companies/{company_id}/teams/{team_id}/tasks.{format} 

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

{"orgId": "4", "teamId": 4, "page": {"pageOffset": 123, "pageSize": 987}}

• REST documentation
• GraphQL documentation

Fields:

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

GET  /api/tasks/v2/tasks/contracts/{engagement_ref}.{format} 

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

{
  "orgId": "4",
  "page": {"pageOffset": 123, "pageSize": 987},
  "filter": {"contractId": 4}
}

• REST documentation
• GraphQL documentation

Fields:

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

GET  /api/otask/v1/tasks/companies/{company_id}/teams/{team_id}/tasks/{code}.{format} 

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

{
  "orgId": "4",
  "teamId": 4,
  "page": {"pageOffset": 123, "pageSize": 987},
  "filter": {"codes": ["xyz789"]}
}

• REST documentation
• GraphQL documentation

Fields:

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

POST  /api/otask/v1/tasks/companies/{company_id}/teams/{team_id}/tasks.{format} 

mutation addTeamActivity(
  $orgId: ID!,
  $teamId: ID!,
  $request: TeamActivityInput!
) {
  addTeamActivity(
    orgId: $orgId
    teamId: $teamId
    request: $request
  ) {
    id
    success
  }
}

{
  "orgId": "4",
  "teamId": 4,
  "request": {
    "code": "abc123",
    "description": "abc123",
    "url": "xyz789",
    "contractIds": [4],
    "allInCompany": true
  }
}

• REST documentation
• GraphQL documentation

Fields:

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

PUT  /api/otask/v1/tasks/companies/{company_id}/teams/{team_id}/tasks/{code}.{format} 

mutation updateTeamActivity(
  $orgId: ID!,
  $teamId: ID!,
  $request: UpdateTeamActivityRequest!
) {
  updateTeamActivity(
    orgId: $orgId
    teamId: $teamId
    request: $request
) {
    success
  }
}

{
  "orgId": "4",
  "teamId": 4,
  "request": {
    "code": "abc123",
    "description": "abc123",
    "url": "xyz789",
    "contractIds": [4],
    "allInCompany": true
  }
}

• REST documentation
• GraphQL documentation

Fields:

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.

PUT  /api/otask/v1/tasks/companies/{company_id}/teams/{team_id}/engagements/{engagement}/tasks.{format} 

mutation assignTeamActivityToTheContract(
  $orgId: ID!,
  $teamId: ID!,
  $contractId: ID!,
  $codes: [String!]!
) {
  assignTeamActivityToTheContract(
    orgId: $orgId
    teamId: $teamId
    contractId: $contractId
    codes: $codes
  ) {
    success
  }
}

{"orgId": "4", "teamId": 4, "contractId": 4, "codes": ["abc123"]}

• REST documentation
• GraphQL documentation

Fields:

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

PUT  /api/otask/v1/tasks/companies/{company_id}/teams/{team_id}/archive/{code}.{format} 

mutation archiveTeamActivity(
  $orgId: ID!,
  $teamId: ID!,
  $codes: [String!]!
) {
  archiveTeamActivity(
    orgId: $orgId
    teamId: $teamId
    codes: $codes
  ) {
    success
  }
}

{"orgId": "4", "teamId": 4, "codes": ["abc123"]}

• REST documentation
• GraphQL documentation

Fields:

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

PUT  /api/otask/v1/tasks/companies/{company_id}/teams/{team_id}/unarchive/{code}.{format} 

mutation unarchiveTeamActivity(
  $orgId: ID!,
  $teamId: ID!,
  $codes: [String!]!
) {
  unarchiveTeamActivity(
    orgId: $orgId
    teamId: $teamId
    codes: $codes
  ) {
    success
  }
}

{"orgId": "4", "teamId": 4, "codes": ["abc123"]}

• REST documentation
• GraphQL documentation

Fields:

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

GET  /api/profiles/v1/metadata/specialties.{format} 

{
  query ontologyCategories {
    ontologyCategories {
      id
      preferredLabel
      altLabel
      slug
      ontologyId
      subcategories {
        ...OntologySubcategoryFragment
      }
      services {
        ...OntologyServiceFragment
      }
    }
  }
}

• REST documentation
• GraphQL documentation

Fields:

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

GET  /api/profiles/v2/metadata/categories.{format} 

{
  query ontologyCategories {
    ontologyCategories {
      id
      preferredLabel
      altLabel
      slug
      ontologyId
      subcategories {
        ...OntologySubcategoryFragment
      }
      services {
        ...OntologyServiceFragment
      }
    }
  }
}

• REST documentation
• GraphQL documentation

Fields:

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

GET  /api/profiles/v2/metadata/skills.{format} 

{
  query ontologyBrowserSkills(
    $limit: Int!,
    $offset: Int
  ) {
    ontologyBrowserSkills(
      limit: $limit,
      offset: $offset
    ) {
      id
      preferredLabel
    }
  }
}

{"limit": 10, "offset": 20}

• REST documentation
• GraphQL documentation

Fields:

This call returns a list of county regions.

GET  /api/profiles/v1/metadata/regions.{format} 

{
  query regions {
    regions {
      id
      name
      parentRegion {
        ...RegionFragment
      }
    }
  }
}

• REST documentation
• GraphQL documentation

Fields:

This call returns a list of reasons by specified type.

GET  /api/profiles/v1/metadata/reasons.{format} 

{
  query reasons(
    $reasonType: ReasonType!,
    $all: Boolean
  ) {
    reasons(
      reasonType: $reasonType,
      all: $all
    ) {
      id
      reason
      alias
    }
  }
}

{"reasonType": "JOB_POSTING_CLOSE", "all": true}

• REST documentation
• GraphQL documentation

Fields:

This API call returns details about the referenced user.

GET  /api/hr/v2/users/{user_reference}
GET /api/hr/v2/users/{user_reference}.{format} 

query userDetails($id: ID!) {
  userDetails(id: $id) {
    id
    nid
    rid
    name
    firstName
    lastName
    photoUrl
    publicUrl
    email
    location {
      timezone
      offsetToUTC
    }
    ciphertext
  }
}

{"id": 4}

• REST documentation
• GraphQL documentation

Fields:

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

GET  /api/profiles/v2/search/jobs.{format} 

query marketplaceJobPostings(
  $marketPlaceJobFilter: MarketplaceJobFilter,
  $searchType: MarketplaceJobPostingSearchType,
  $sortAttributes: [MarketplaceJobPostingSearchSortAttribute]
) {
  marketplaceJobPostings(
    marketPlaceJobFilter: $marketPlaceJobFilter,
    searchType: $searchType,
    sortAttributes: $sortAttributes
  ) {
    totalCount
    edges {
      ...MarketplaceJobpostingSearchEdgeFragment
    }
    pageInfo {
      ...PageInfoFragment
    }
  }
}

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

• REST documentation
• GraphQL documentation

Fields:

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.

GET  /api/hr/v2/jobs.{format} 

{
    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
                }
            }
        }
    }
}

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

• REST documentation
• GraphQL documentation

Fields:

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.

GET  /api/hr/v2/jobs/{job_key}.{format} 

{
    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
    }
}

{"jobPostingId": 4}

• REST documentation
• GraphQL documentation

Fields:

Gets a specific snapshot

GET  /api/team/v3/snapshots/contracts/{contract_id}/{timestamp}.{format} 

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

{"contractId": "123456", "timestamp": "123456"}

• REST documentation
• GraphQL documentation

Fields:

This call allows company owners to see what their freelancers get paid. Disallowed fields: `comment`, `po_number`. Supported filters: `date`, `week`, `month`, `year`, `date_due`, `provider_company__reference`, `provider_company__id`, `provider__reference`, `provider__id`, `assignment__reference`, `type`, `subtype`. Permissions: owner or admin.

GET  /gds/finreports/v2/buyer_companies/{buyer_company_ref}/billings 

query TransactionHistory($aceIds_any: [ID!]!, $transactionDateTime_bt: DateTimeRange!) {
  transactionHistory(
    transactionHistoryFilter: {aceIds_any: $aceIds_any, transactionDateTime_bt: $transactionDateTime_bt}
  ) {
    transactionDetail {
      transactionHistoryRow {
        rowNumber
        runningChargeableBalance {
          rawValue
          currency
          displayValue
        }
        recordId
        remainder
        amountCreditedToUser {
          rawValue
          currency
          displayValue
        }
        transactionReviewDueDate
        transactionCreationDate
        relatedUserPaymentMethod
        accountingSubtype
        descriptionUI
        relatedAssignment
        amountSentInOrigCurrency {
          rawValue
          currency
          displayValue
        }
        paymentGuaranteed
        fixedPriceEARMark
        relatedTransactionId
        relatedInvoiceId
        fullyPaidDate
        type
        transactionAmount {
          rawValue
          currency
          displayValue
        }
        relatedAccountingEntity
        description
        purchaseOrderNumber
        assignmentAgencyName
        assignmentCompanyName
        assignmentDeveloperName
        assignmentTeamCompanyId
        assignmentTeamCompanyReference
        assignmentTeamId
        assignmentTeamReference
        assignmentTeamUserId
        assignmentTeamUserReference
        payment {
          rawValue
          currency
          displayValue
        }
        paymentStatus
      }
    }
  }
}

• REST documentation
• GraphQL documentation

Fields:

This call allows company owners to see what they pay to their freelancers. Disallowed fields: none. Supported filters: `date`, `week`, `month`, `year`, `date_due`, `provider_company__reference`, `provider_company__id`, `provider__reference`, `provider__id`, `assignment__reference`, `type`, `subtype`, `po_number`. Permissions: owner or admin.

GET  /gds/finreports/v2/buyer_companies/{buyer_company_ref}/earnings 

query TransactionHistory($aceIds_any: [ID!]!, $transactionDateTime_bt: DateTimeRange!) {
  transactionHistory(
    transactionHistoryFilter: {aceIds_any: $aceIds_any, transactionDateTime_bt: $transactionDateTime_bt}
  ) {
    transactionDetail {
      transactionHistoryRow {
        rowNumber
        runningChargeableBalance {
          rawValue
          currency
          displayValue
        }
        recordId
        remainder
        amountCreditedToUser {
          rawValue
          currency
          displayValue
        }
        transactionReviewDueDate
        transactionCreationDate
        relatedUserPaymentMethod
        accountingSubtype
        descriptionUI
        relatedAssignment
        amountSentInOrigCurrency {
          rawValue
          currency
          displayValue
        }
        paymentGuaranteed
        fixedPriceEARMark
        relatedTransactionId
        relatedInvoiceId
        fullyPaidDate
        type
        transactionAmount {
          rawValue
          currency
          displayValue
        }
        relatedAccountingEntity
        description
        purchaseOrderNumber
        assignmentAgencyName
        assignmentCompanyName
        assignmentDeveloperName
        assignmentTeamCompanyId
        assignmentTeamCompanyReference
        assignmentTeamId
        assignmentTeamReference
        assignmentTeamUserId
        assignmentTeamUserReference
        payment {
          rawValue
          currency
          displayValue
        }
        paymentStatus
      }
    }
  }
}

• REST documentation
• GraphQL documentation

Time reports can be generated at company-wide level. In order to access this call the authorized user needs either hiring or finance permissions to all teams within the company

GET  /gds/timereports/v1/companies/{company_id} 

query timeReport($orgId: ID!, $after: String, $first: Int!, $timeReportDate_bt: DateTimeRange!) {
  contractTimeReport(
    filter: {organizationId_eq: $orgId, timeReportDate_bt: $timeReportDate_bt}
    pagination: {after: $after, first: $first}
  ) {
    totalCount
    edges {
      cursor
      node {
        dateWorkedOn
        weekWorkedOn
        monthWorkedOn
        yearWorkedOn
        freelancer {
          id
          nid
          name
        }
        team {
          id
          name
        }
        contract {
          id
        }
        task
        taskDescription
        memo
        totalHoursWorked
        totalCharges
        totalOnlineHoursWorked
        totalOnlineCharge
        totalOfflineHoursWorked
        totalOfflineCharge
      }
    }
  }
}

• REST documentation
• GraphQL documentation

Fields:

GraphQL OAuth2 scopes:

This call generates time report for a team without detailed monetary information (charges, etc.), only information about hours. Note that if the `provider_id` field is present in the query, the caller must be a supervisor of the freelancers. If the `provider_id` is not provided in the query, the caller must have either hiring manager or finance permission to the specified team.

GET  /gds/timereports/v1/companies/{company_id}/teams/{team_id}/hours 

query timeReport($orgId: ID!, $after: String, $first: Int!, $timeReportDate_bt: DateTimeRange!) {
  contractTimeReport(
    filter: {organizationId_eq: $orgId, timeReportDate_bt: $timeReportDate_bt}
    pagination: {after: $after, first: $first}
  ) {
    totalCount
    edges {
      cursor
      node {
        dateWorkedOn
        weekWorkedOn
        monthWorkedOn
        yearWorkedOn
        freelancer {
          id
          nid
          name
        }
        team {
          id
          name
        }
        contract {
          id
        }
        task
        taskDescription
        memo
        totalHoursWorked
        totalCharges
        totalOnlineHoursWorked
        totalOnlineCharge
        totalOfflineHoursWorked
        totalOfflineCharge
      }
    }
  }
}

• REST documentation
• GraphQL documentation