HubSpot Deals API

openapi: 3.1.0
info:
  title: HubSpot CRM Deals API
  description: >-
    A deal stores data about an ongoing transaction or sales opportunity. The
    deals endpoints allow you to manage deal records and sync data between
    HubSpot and other systems, supporting the full lifecycle of sales
    opportunities through pipeline stages.
  version: v3
  contact:
    name: HubSpot Developer Support
    url: https://developers.hubspot.com/
servers:
- url: https://api.hubapi.com
  description: HubSpot API
security:
- oauth2: []
tags:
- name: Associations
  description: Operations for managing deal associations
- name: Batch
  description: Batch operations for deals
- name: Deals
  description: Operations for managing deal records
paths:
  /crm/v3/objects/deals:
    get:
      operationId: listDeals
      summary: Hubspot List Deals
      description: >-
        Returns a page of deal records. Use the limit and after parameters
        to paginate through deals. You can also specify which properties to
        return using the properties parameter.
      tags:
      - Deals
      parameters:
      - name: limit
        in: query
        description: The maximum number of results to return per page.
        schema:
          type: integer
          default: 10
          maximum: 100
        example: 10
      - name: after
        in: query
        description: The cursor for pagination to get the next page of results.
        schema:
          type: string
        example: example-value
      - name: properties
        in: query
        description: A comma-separated list of property names to return.
        schema:
          type: string
        example: example-value
      - name: archived
        in: query
        description: Whether to return archived deals.
        schema:
          type: boolean
          default: false
        example: false
      responses:
        '200':
          description: Successful response with a list of deals.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseDeal'
              examples:
                Listdeals200Example:
                  summary: Default listDeals 200 response
                  x-microcks-default: true
                  value:
                    results: &id005
                    - id: '500123'
                      properties: &id001
                        key: value
                      createdAt: '2025-03-15T14:30:00Z'
                      updatedAt: '2025-03-15T14:30:00Z'
                      archived: true
                      associations: &id002
                        key: value
                    paging:
                      next: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createDeal
      summary: Hubspot Create a Deal
      description: >-
        Creates a new deal record with the provided properties. The request
        body should include a properties object containing the field values
        for the deal you want to create, including dealname, amount, and
        pipeline stage.
      tags:
      - Deals
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimplePublicObjectInput'
            examples:
              CreatedealRequestExample:
                summary: Default createDeal request
                x-microcks-default: true
                value:
                  properties: &id003
                    key: value
      responses:
        '201':
          description: Deal created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deal'
              examples:
                Createdeal201Example:
                  summary: Default createDeal 201 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    properties: *id001
                    createdAt: '2025-03-15T14:30:00Z'
                    updatedAt: '2025-03-15T14:30:00Z'
                    archived: true
                    associations: *id002
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /crm/v3/objects/deals/{dealId}:
    get:
      operationId: getDeal
      summary: Hubspot Get a Deal
      description: >-
        Returns a single deal record by its ID. You can specify which
        properties to return using the properties parameter.
      tags:
      - Deals
      parameters:
      - name: dealId
        in: path
        required: true
        description: The ID of the deal to retrieve.
        schema:
          type: string
        example: '500123'
      - name: properties
        in: query
        description: A comma-separated list of property names to return.
        schema:
          type: string
        example: example-value
      - name: archived
        in: query
        description: Whether to return archived deals.
        schema:
          type: boolean
          default: false
        example: false
      responses:
        '200':
          description: Successful response with the deal record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deal'
              examples:
                Getdeal200Example:
                  summary: Default getDeal 200 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    properties: *id001
                    createdAt: '2025-03-15T14:30:00Z'
                    updatedAt: '2025-03-15T14:30:00Z'
                    archived: true
                    associations: *id002
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updateDeal
      summary: Hubspot Update a Deal
      description: >-
        Performs a partial update of a deal record. Only the properties
        included in the request body will be updated; other properties will
        remain unchanged.
      tags:
      - Deals
      parameters:
      - name: dealId
        in: path
        required: true
        description: The ID of the deal to update.
        schema:
          type: string
        example: '500123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimplePublicObjectInput'
            examples:
              UpdatedealRequestExample:
                summary: Default updateDeal request
                x-microcks-default: true
                value:
                  properties: *id003
      responses:
        '200':
          description: Deal updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Deal'
              examples:
                Updatedeal200Example:
                  summary: Default updateDeal 200 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    properties: *id001
                    createdAt: '2025-03-15T14:30:00Z'
                    updatedAt: '2025-03-15T14:30:00Z'
                    archived: true
                    associations: *id002
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteDeal
      summary: Hubspot Archive a Deal
      description: >-
        Archives (soft deletes) a deal record by its ID. Archived deals
        can be restored using the HubSpot UI or API. This does not permanently
        delete the deal from HubSpot.
      tags:
      - Deals
      parameters:
      - name: dealId
        in: path
        required: true
        description: The ID of the deal to archive.
        schema:
          type: string
        example: '500123'
      responses:
        '204':
          description: Deal archived successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /crm/v3/objects/deals/batch/read:
    post:
      operationId: batchReadDeals
      summary: Hubspot Batch Read Deals
      description: >-
        Reads a batch of deal records by their IDs or unique property values.
        Useful for retrieving multiple deals in a single API call.
      tags:
      - Batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchReadInput'
            examples:
              BatchreaddealsRequestExample:
                summary: Default batchReadDeals request
                x-microcks-default: true
                value:
                  properties: &id006
                  - example-value
                  inputs: &id007
                  - id: '500123'
      responses:
        '200':
          description: Batch read completed successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponseDeal'
              examples:
                Batchreaddeals200Example:
                  summary: Default batchReadDeals 200 response
                  x-microcks-default: true
                  value:
                    status: active
                    results: &id004
                    - id: '500123'
                      properties: *id001
                      createdAt: '2025-03-15T14:30:00Z'
                      updatedAt: '2025-03-15T14:30:00Z'
                      archived: true
                      associations: *id002
                    completedAt: '2025-03-15T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /crm/v3/objects/deals/batch/create:
    post:
      operationId: batchCreateDeals
      summary: Hubspot Batch Create Deals
      description: >-
        Creates multiple deal records in a single API call. The request
        body should include an array of deal property objects.
      tags:
      - Batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCreateInput'
            examples:
              BatchcreatedealsRequestExample:
                summary: Default batchCreateDeals request
                x-microcks-default: true
                value:
                  inputs: &id008
                  - properties: *id003
      responses:
        '201':
          description: Deals created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponseDeal'
              examples:
                Batchcreatedeals201Example:
                  summary: Default batchCreateDeals 201 response
                  x-microcks-default: true
                  value:
                    status: active
                    results: *id004
                    completedAt: '2025-03-15T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /crm/v3/objects/deals/batch/update:
    post:
      operationId: batchUpdateDeals
      summary: Hubspot Batch Update Deals
      description: >-
        Updates multiple deal records in a single API call. Each record
        in the request must include the deal ID and the properties to update.
      tags:
      - Batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchUpdateInput'
            examples:
              BatchupdatedealsRequestExample:
                summary: Default batchUpdateDeals request
                x-microcks-default: true
                value:
                  inputs: &id009
                  - id: '500123'
                    properties:
                      key: value
      responses:
        '200':
          description: Deals updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponseDeal'
              examples:
                Batchupdatedeals200Example:
                  summary: Default batchUpdateDeals 200 response
                  x-microcks-default: true
                  value:
                    status: active
                    results: *id004
                    completedAt: '2025-03-15T14:30:00Z'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /crm/v3/objects/deals/batch/archive:
    post:
      operationId: batchArchiveDeals
      summary: Hubspot Batch Archive Deals
      description: >-
        Archives multiple deal records in a single API call by their IDs.
        Archived deals can be restored using the HubSpot UI or API.
      tags:
      - Batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchArchiveInput'
            examples:
              BatcharchivedealsRequestExample:
                summary: Default batchArchiveDeals request
                x-microcks-default: true
                value:
                  inputs: &id010
                  - id: '500123'
      responses:
        '204':
          description: Deals archived successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /crm/v3/objects/deals/search:
    post:
      operationId: searchDeals
      summary: Hubspot Search Deals
      description: >-
        Searches for deal records using filter groups, sorts, and other
        query parameters. Supports complex filtering with multiple filter
        groups and operators for precise record retrieval.
      tags:
      - Deals
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            examples:
              SearchdealsRequestExample:
                summary: Default searchDeals request
                x-microcks-default: true
                value:
                  filterGroups: &id011
                  - filters:
                    - {}
                  sorts: &id012
                  - propertyName: Example Record
                    direction: ASCENDING
                  query: example-value
                  properties: &id013
                  - example-value
                  limit: 100
                  after: example-value
      responses:
        '200':
          description: Search results returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseDeal'
              examples:
                Searchdeals200Example:
                  summary: Default searchDeals 200 response
                  x-microcks-default: true
                  value:
                    results: *id005
                    paging:
                      next: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /crm/v3/objects/deals/{dealId}/associations/{toObjectType}:
    get:
      operationId: listDealAssociations
      summary: Hubspot List Deal Associations
      description: >-
        Returns all associations of a deal record to objects of a specified
        type, such as contacts, companies, or tickets.
      tags:
      - Associations
      parameters:
      - name: dealId
        in: path
        required: true
        description: The ID of the deal.
        schema:
          type: string
        example: '500123'
      - name: toObjectType
        in: path
        required: true
        description: The type of associated object (e.g., contacts, companies).
        schema:
          type: string
        example: standard
      responses:
        '200':
          description: List of associations returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseAssociation'
              examples:
                Listdealassociations200Example:
                  summary: Default listDealAssociations 200 response
                  x-microcks-default: true
                  value:
                    results: &id014
                    - id: '500123'
                      type: standard
                    paging:
                      next: {}
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /crm/v3/objects/deals/{dealId}/associations/{toObjectType}/{toObjectId}/{associationType}:
    put:
      operationId: createDealAssociation
      summary: Hubspot Create a Deal Association
      description: >-
        Creates an association between a deal and another CRM object record.
        The association type specifies the relationship between the objects.
      tags:
      - Associations
      parameters:
      - name: dealId
        in: path
        required: true
        description: The ID of the deal.
        schema:
          type: string
        example: '500123'
      - name: toObjectType
        in: path
        required: true
        description: The type of the object to associate with.
        schema:
          type: string
        example: standard
      - name: toObjectId
        in: path
        required: true
        description: The ID of the object to associate with.
        schema:
          type: string
        example: '500123'
      - name: associationType
        in: path
        required: true
        description: The type of association to create.
        schema:
          type: string
        example: standard
      responses:
        '200':
          description: Association created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Association'
              examples:
                Createdealassociation200Example:
                  summary: Default createDealAssociation 200 response
                  x-microcks-default: true
                  value:
                    id: '500123'
                    type: standard
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteDealAssociation
      summary: Hubspot Delete a Deal Association
      description: >-
        Removes an association between a deal and another CRM object record.
        This does not delete the deal or the associated object, only the
        relationship between them.
      tags:
      - Associations
      parameters:
      - name: dealId
        in: path
        required: true
        description: The ID of the deal.
        schema:
          type: string
        example: '500123'
      - name: toObjectType
        in: path
        required: true
        description: The type of the associated object.
        schema:
          type: string
        example: standard
      - name: toObjectId
        in: path
        required: true
        description: The ID of the associated object.
        schema:
          type: string
        example: '500123'
      - name: associationType
        in: path
        required: true
        description: The type of association to delete.
        schema:
          type: string
        example: standard
      responses:
        '204':
          description: Association deleted successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  securitySchemes:
    oauth2:
      type: http
      scheme: bearer
      description: OAuth 2.0 Bearer token (access token from OAuth flow)
  schemas:
    Deal:
      type: object
      description: A HubSpot deal record.
      properties:
        id:
          type: string
          description: The unique identifier for the deal.
          example: '500123'
        properties:
          type: object
          description: The deal's properties as key-value pairs.
          additionalProperties:
            type: string
          example: *id001
        createdAt:
          type: string
          format: date-time
          description: The date and time the deal was created.
          example: '2025-03-15T14:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: The date and time the deal was last updated.
          example: '2025-03-15T14:30:00Z'
        archived:
          type: boolean
          description: Whether the deal has been archived.
          example: true
        associations:
          type: object
          description: The deal's associations with other CRM objects.
          additionalProperties:
            $ref: '#/components/schemas/CollectionResponseAssociation'
          example: *id002
    CollectionResponseDeal:
      type: object
      description: A paginated list of deal records.
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Deal'
          example: *id005
        paging:
          $ref: '#/components/schemas/Paging'
    BatchResponseDeal:
      type: object
      description: Results from a batch operation on deals.
      properties:
        status:
          type: string
          example: active
        results:
          type: array
          items:
            $ref: '#/components/schemas/Deal'
          example: *id004
        completedAt:
          type: string
          format: date-time
          example: '2025-03-15T14:30:00Z'
    SimplePublicObjectInput:
      type: object
      description: Input for creating or updating a CRM object.
      properties:
        properties:
          type: object
          additionalProperties:
            type: string
          example: *id003
    BatchReadInput:
      type: object
      description: Input for a batch read operation.
      properties:
        properties:
          type: array
          items:
            type: string
          example: *id006
        inputs:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
          example: *id007
    BatchCreateInput:
      type: object
      description: Input for a batch create operation.
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/SimplePublicObjectInput'
          example: *id008
    BatchUpdateInput:
      type: object
      description: Input for a batch update operation.
      properties:
        inputs:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              properties:
                type: object
                additionalProperties:
                  type: string
          example: *id009
    BatchArchiveInput:
      type: object
      description: Input for a batch archive operation.
      properties:
        inputs:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
          example: *id010
    SearchRequest:
      type: object
      description: A search request for CRM objects.
      properties:
        filterGroups:
          type: array
          items:
            $ref: '#/components/schemas/FilterGroup'
          example: *id011
        sorts:
          type: array
          items:
            type: object
            properties:
              propertyName:
                type: string
              direction:
                type: string
                enum: [ASCENDING, DESCENDING]
          example: *id012
        query:
          type: string
          example: example-value
        properties:
          type: array
          items:
            type: string
          example: *id013
        limit:
          type: integer
          maximum: 200
          example: 100
        after:
          type: string
          example: example-value
    FilterGroup:
      type: object
      description: A group of filters combined with AND logic.
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/Filter'
          example:
          - propertyName: Example Record
            operator: EQ
            value: example-value
    Filter:
      type: object
      description: A single filter condition.
      properties:
        propertyName:
          type: string
          example: Example Record
        operator:
          type: string
          enum: [EQ, NEQ, LT, LTE, GT, GTE, BETWEEN, IN, NOT_IN, HAS_PROPERTY, NOT_HAS_PROPERTY, CONTAINS_TOKEN, NOT_CONTAINS_TOKEN]
          example: EQ
        value:
          type: string
          example: example-value
    Association:
      type: object
      description: An association between two CRM objects.
      properties:
        id:
          type: string
          example: '500123'
        type:
          type: string
          example: standard
    CollectionResponseAssociation:
      type: object
      description: A list of associations.
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Association'
          example: *id014
        paging:
          $ref: '#/components/schemas/Paging'
    Paging:
      type: object
      description: Pagination information.
      properties:
        next:
          type: object
          properties:
            after:
              type: string
          example:
            after: example-value
    Error:
      type: object
      description: An error response.
      properties:
        status:
          type: string
          example: active
        message:
          type: string
          example: This is an example description.
        correlationId:
          type: string
          example: '500123'
        category:
          type: string
          example: standard
  responses:
    Unauthorized:
      description: Authentication credentials are missing or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    BadRequest:
      description: The request is invalid or missing required parameters.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'