Upwork Contracts API

openapi: 3.0.3
info:
  title: Upwork GraphQL Authentication Contracts API
  description: The primary Upwork API surface, providing GraphQL queries and mutations for job search, profile access, contract management, and messaging. The API is accessed at a single GraphQL endpoint using POST requests with JSON bodies containing queries and variables. Authentication uses OAuth 2.0 authorization code flow with Bearer tokens. GraphQL subscriptions are supported for real-time webhook event notifications.
  version: 1.0.0
  contact:
    name: Upwork Developer Support
    url: https://support.upwork.com/hc/en-us/sections/17976982721555-Upwork-API
  termsOfService: https://www.upwork.com/legal
  x-generated-from: documentation
servers:
- url: https://api.upwork.com
  description: Upwork Production API
security:
- oauth2AuthCode: []
tags:
- name: Contracts
  description: Access and manage freelance contracts including terms, milestones, and time entries.
paths:
  /graphql:
    post:
      operationId: executeGraphQL
      summary: Upwork Execute GraphQL Query or Mutation
      description: Execute a GraphQL query, mutation, or subscription against the Upwork API. All GraphQL operations are sent as POST requests to this endpoint with a JSON body containing the query, optional variables, and optional operation name. Returns JSON with data and optional errors fields.
      tags:
      - Contracts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GraphQLRequest'
            examples:
              searchJobs:
                summary: Search for jobs using marketplaceJobPostingsSearch
                value:
                  query: "query SearchJobs($searchExpression: String, $paging: PagingInput) {\n  marketplaceJobPostingsSearch(searchExpression: $searchExpression, paging: $paging) {\n    total\n    results {\n      id\n      title\n      description\n      skills { name }\n      budget { amount currency }\n      createdDateTime\n      client { id country }\n    }\n  }\n}\n"
                  variables:
                    searchExpression: python developer
                    paging:
                      offset: 0
                      count: 10
      responses:
        '200':
          description: GraphQL response with data or errors
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GraphQLResponse'
              examples:
                jobSearchResponse:
                  summary: Job search results
                  x-microcks-default: true
                  value:
                    data:
                      marketplaceJobPostingsSearch:
                        total: 1250
                        results:
                        - id: ~0123456789abcdef
                          title: Python Developer for Data Pipeline
                          description: Looking for an experienced Python developer...
                          skills:
                          - name: Python
                          - name: Data Engineering
                          budget:
                            amount: 5000
                            currency: USD
                          createdDateTime: '2025-03-15T14:30:00Z'
        '401':
          description: Unauthorized - invalid or missing OAuth2 token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v3/hr/v2/contracts:
    get:
      operationId: listContracts
      summary: Upwork List Contracts
      description: Retrieve a list of contracts for the authenticated user. Includes both active and completed contracts with status, terms, and financial data.
      tags:
      - Contracts
      parameters:
      - name: status
        in: query
        description: Filter by contract status
        schema:
          type: string
          enum:
          - active
          - closed
          - paused
        example: active
      - name: buyer_team__reference
        in: query
        description: Filter by buyer team reference ID
        schema:
          type: string
        example: team-abc123
      - name: paging
        in: query
        description: Pagination as offset;count
        schema:
          type: string
        example: 0;20
      responses:
        '200':
          description: List of contracts
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ContractListResponse'
              examples:
                listContracts200Example:
                  summary: Default listContracts 200 response
                  x-microcks-default: true
                  value:
                    total: 25
                    contracts:
                    - id: contract-abc123
                      status: active
                      jobTitle: Python Developer for Data Pipeline
                      freelancerName: Jane Smith
                      rate: 75.0
                      currency: USD
                      startedTime: '2025-01-15T10:00:00Z'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /api/v3/hr/v2/contracts/{contract_id}:
    get:
      operationId: getContract
      summary: Upwork Get Contract Details
      description: Retrieve detailed information for a specific contract including terms, milestones, time entries, and financial summary.
      tags:
      - Contracts
      parameters:
      - name: contract_id
        in: path
        required: true
        description: The unique identifier of the contract
        schema:
          type: string
        example: contract-abc123
      responses:
        '200':
          description: Contract details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Contract'
              examples:
                getContract200Example:
                  summary: Default getContract 200 response
                  x-microcks-default: true
                  value:
                    id: contract-abc123
                    status: active
                    jobTitle: Python Developer for Data Pipeline
                    rate: 75.0
                    currency: USD
        '404':
          description: Contract not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/APIError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Contract:
      type: object
      description: A freelance contract between a client and freelancer on Upwork
      properties:
        id:
          type: string
          description: Unique identifier for the contract
          example: contract-abc123
        status:
          type: string
          description: Current status of the contract
          enum:
          - active
          - paused
          - closed
          example: active
        jobTitle:
          type: string
          description: Title of the job associated with this contract
          example: Python Developer for Data Pipeline
        freelancerId:
          type: string
          description: ID of the freelancer on the contract
          example: ~abc123
        freelancerName:
          type: string
          description: Name of the freelancer
          example: Jane Smith
        clientId:
          type: string
          description: ID of the client
          example: ~def456
        rate:
          type: number
          description: Hourly or fixed rate for the contract
          example: 75.0
        currency:
          type: string
          description: Currency for the contract rate
          example: USD
        startedTime:
          type: string
          format: date-time
          description: When the contract started
          example: '2025-01-15T10:00:00Z'
        endedTime:
          type: string
          format: date-time
          description: When the contract ended (if closed)
          example: '2025-03-15T10:00:00Z'
    GraphQLRequest:
      type: object
      description: A GraphQL request body containing the operation to execute
      required:
      - query
      properties:
        query:
          type: string
          description: The GraphQL query or mutation string
          example: 'query { marketplaceJobPostingsSearch(searchExpression: "python") { total } }'
        variables:
          type: object
          description: Variables for the GraphQL operation
          additionalProperties: true
        operationName:
          type: string
          description: Name of the operation to execute (for documents with multiple operations)
          example: SearchJobs
    APIError:
      type: object
      description: API error response
      properties:
        error:
          type: string
          description: Error code
          example: unauthorized
        message:
          type: string
          description: Human-readable error message
          example: Authentication failed. Please check your credentials.
        code:
          type: integer
          description: HTTP status code
          example: 401
    ContractListResponse:
      type: object
      description: Paginated list of contracts
      properties:
        total:
          type: integer
          description: Total number of contracts
          example: 25
        contracts:
          type: array
          description: List of contracts
          items:
            $ref: '#/components/schemas/Contract'
    GraphQLError:
      type: object
      description: A GraphQL error
      properties:
        message:
          type: string
          description: Human-readable error message
          example: Unauthorized access
        locations:
          type: array
          description: Source locations of the error
          items:
            type: object
            properties:
              line:
                type: integer
                example: 2
              column:
                type: integer
                example: 5
        path:
          type: array
          description: Path to the field that caused the error
          items:
            type: string
    GraphQLResponse:
      type: object
      description: A GraphQL response containing data or errors
      properties:
        data:
          type: object
          description: The response data for the operation
          additionalProperties: true
        errors:
          type: array
          description: List of GraphQL errors if the operation failed
          items:
            $ref: '#/components/schemas/GraphQLError'
  securitySchemes:
    oauth2AuthCode:
      type: oauth2
      description: OAuth 2.0 authorization code flow for Upwork API access. Obtain an authorization code by redirecting users to the Upwork OAuth consent page, then exchange for access and refresh tokens.
      flows:
        authorizationCode:
          authorizationUrl: https://www.upwork.com/ab/account-security/oauth2/authorize
          tokenUrl: https://www.upwork.com/api/v3/oauth2/token
          scopes:
            openid: Access to user identity information
            email: Access to user email
            profile: Access to user profile data
            jobs:read: Read job postings
            contracts:read: Read contract data
            messages:read: Read messages
            messages:write: Send messages
            profiles:read: Read freelancer profiles
            reports:read: Read financial reports
externalDocs:
  description: Upwork GraphQL API Documentation
  url: https://www.upwork.com/developer/documentation/graphql/api/docs/index.html