HubSpot CRM Contracts API

openapi: 3.0.1
info:
  title: HubSpot CRM Contracts
  description: Basepom for all HubSpot Projects
  version: 2026-03
  x-hubspot-product-tier-requirements:
    marketing: FREE
    sales: FREE
    service: FREE
    cms: FREE
    commerce: FREE
    crmHub: FREE
    dataHub: FREE
servers:
- url: https://api.hubapi.com
tags:
- name: Basic
- name: Batch
paths:
  /crm/objects/2026-03/contracts:
    get:
      tags:
      - Basic
      summary: List
      description: Read a page of contracts. Control what is returned via the `properties` query param.
      operationId: get-/crm/objects/2026-03/contracts
      parameters:
      - name: after
        in: query
        description: The paging cursor token of the last successfully read resource will be returned as
          the `paging.next.after` JSON property of a paged response containing more results.
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: false
      - name: associations
        in: query
        description: A comma separated list of object types to retrieve associated IDs for. If any of
          the specified associations do not exist, they will be ignored.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: limit
        in: query
        description: The maximum number of results to display per page.
        required: false
        style: form
        explode: true
        schema:
          type: integer
          format: int32
          default: 10
      - name: properties
        in: query
        description: A comma separated list of the properties to be returned in the response. If any of
          the specified properties are not present on the requested object(s), they will be ignored.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: propertiesWithHistory
        in: query
        description: A comma separated list of the properties to be returned along with their history
          of previous values. If any of the specified properties are not present on the requested object(s),
          they will be ignored. Usage of this parameter will reduce the maximum number of contracts that
          can be read by a single request.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseSimplePublicObjectWithAssociationsForwardPaging'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.objects.contracts.read
      x-hubspot-user-level-auth:
        internalOnly: false
  /crm/objects/2026-03/contracts/batch/read:
    post:
      tags:
      - Batch
      summary: Read a batch of contracts by internal ID, or unique property values
      description: 'Retrieve records by record ID or include the `idProperty` parameter to retrieve records
        by a custom unique value property. '
      operationId: post-/crm/objects/2026-03/contracts/batch/read_read
      parameters:
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: false
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchReadInputSimplePublicObjectId'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponseSimplePublicObject'
        '207':
          description: multiple statuses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponseSimplePublicObjectWithErrors'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.objects.contracts.read
      x-hubspot-user-level-auth:
        internalOnly: false
  /crm/objects/2026-03/contracts/{contractId}:
    get:
      tags:
      - Basic
      summary: Read
      description: Read an Object identified by `{contractId}`. `{contractId}` refers to the internal
        object ID by default, or optionally any unique property value as specified by the `idProperty`
        query param.  Control what is returned via the `properties` query param.
      operationId: get-/crm/objects/2026-03/contracts/{contractId}
      parameters:
      - name: contractId
        in: path
        required: true
        schema:
          pattern: .+
          type: string
      - name: archived
        in: query
        description: Whether to return only results that have been archived.
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: false
      - name: associations
        in: query
        description: A comma separated list of object types to retrieve associated IDs for. If any of
          the specified associations do not exist, they will be ignored.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: idProperty
        in: query
        description: The name of a property whose values are unique for this object type
        required: false
        style: form
        explode: true
        schema:
          type: string
      - name: properties
        in: query
        description: A comma separated list of the properties to be returned in the response. If any of
          the specified properties are not present on the requested object(s), they will be ignored.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      - name: propertiesWithHistory
        in: query
        description: A comma separated list of the properties to be returned along with their history
          of previous values. If any of the specified properties are not present on the requested object(s),
          they will be ignored.
        required: false
        style: form
        explode: true
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimplePublicObjectWithAssociations'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.objects.contracts.read
      x-hubspot-user-level-auth:
        internalOnly: false
components:
  schemas:
    AssociatedId:
      required:
      - id
      - type
      type: object
      properties:
        id:
          type: string
          description: The ID for the association type.
        type:
          type: string
          description: The type of associations.
          example: deal_to_contact
      description: Contains the id and type of an association
    BatchReadInputSimplePublicObjectId:
      required:
      - inputs
      - properties
      - propertiesWithHistory
      type: object
      properties:
        idProperty:
          type: string
          description: When using a custom unique value property to retrieve records, the name of the
            property. Do not include this parameter if retrieving by record ID.
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/SimplePublicObjectId'
        properties:
          type: array
          description: Key-value pairs for setting properties for the new object.
          items:
            type: string
        propertiesWithHistory:
          type: array
          description: Key-value pairs for setting properties for the new object and their histories.
          items:
            type: string
      description: Specifies the input for reading a batch of CRM objects, including arrays of object
        IDs, requested property names (with optional history), and an optional unique identifying property.
    BatchResponseSimplePublicObject:
      required:
      - completedAt
      - results
      - startedAt
      - status
      type: object
      properties:
        completedAt:
          type: string
          description: The timestamp when the batch processing was completed, in ISO 8601 format.
          format: date-time
        links:
          type: object
          additionalProperties:
            type: string
          description: An object containing relevant links related to the batch request.
        requestedAt:
          type: string
          description: The timestamp when the batch request was initially made, in ISO 8601 format.
          format: date-time
        results:
          type: array
          items:
            $ref: '#/components/schemas/SimplePublicObject'
        startedAt:
          type: string
          description: The timestamp when the batch processing began, in ISO 8601 format.
          format: date-time
        status:
          type: string
          description: 'The status of the batch processing request: "PENDING", "PROCESSING", "CANCELLED",
            or "COMPLETE"'
          enum:
          - CANCELED
          - COMPLETE
          - PENDING
          - PROCESSING
      description: A public object batch response object
    BatchResponseSimplePublicObjectWithErrors:
      required:
      - completedAt
      - results
      - startedAt
      - status
      type: object
      properties:
        completedAt:
          type: string
          description: The timestamp when the batch process was completed, in ISO 8601 format.
          format: date-time
        errors:
          type: array
          items:
            $ref: '#/components/schemas/StandardError'
        links:
          type: object
          additionalProperties:
            type: string
          description: An object containing relevant links related to the batch request.
        numErrors:
          type: integer
          description: The number of errors encountered during the batch process.
          format: int32
        requestedAt:
          type: string
          description: The timestamp when the batch process was initiated, in ISO 8601 format.
          format: date-time
        results:
          type: array
          items:
            $ref: '#/components/schemas/SimplePublicObject'
        startedAt:
          type: string
          description: The timestamp when the batch process began execution, in ISO 8601 format.
          format: date-time
        status:
          type: string
          description: The status of the batch processing request - "PENDING", "PROCESSING", "CANCELLED",
            or "COMPLETE"
          enum:
          - CANCELED
          - COMPLETE
          - PENDING
          - PROCESSING
      description: Represents the result of a batch operation on CRM objects, including the processing
        status, batch results, timestamps, and a list of any errors encountered during the operation.
    CollectionResponseAssociatedId:
      required:
      - results
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/Paging'
        results:
          type: array
          items:
            $ref: '#/components/schemas/AssociatedId'
    CollectionResponseSimplePublicObjectWithAssociationsForwardPaging:
      required:
      - results
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/ForwardPaging'
        results:
          type: array
          items:
            $ref: '#/components/schemas/SimplePublicObjectWithAssociations'
    Error:
      required:
      - category
      - correlationId
      - message
      type: object
      properties:
        category:
          type: string
          description: The error category
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Context about the error condition
          example: '{invalidPropertyName=[propertyValue], missingScopes=[scope1, scope2]}'
        correlationId:
          type: string
          description: A unique identifier for the request. Include this value with any error reports
            or support tickets
          format: uuid
          example: aeb5f871-7f07-4993-9211-075dc63e7cbf
        errors:
          type: array
          description: further information about the error
          items:
            $ref: '#/components/schemas/ErrorDetail'
        links:
          type: object
          additionalProperties:
            type: string
          description: A map of link names to associated URIs containing documentation about the error
            or recommended remediation steps
        message:
          type: string
          description: A human readable message describing the error along with remediation steps where
            appropriate
          example: An error occurred
        subCategory:
          type: string
          description: A specific category that contains more specific detail about the error
      description: Represents an error response returned by the API when an operation fails. This component
        is used in various endpoints to provide detailed information about the error encountered.
      example:
        message: Invalid input (details will vary based on the error)
        correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
        category: VALIDATION_ERROR
        links:
          knowledge-base: https://www.hubspot.com/products/service/knowledge-base
    ErrorDetail:
      required:
      - message
      type: object
      properties:
        code:
          type: string
          description: The status code associated with the error detail
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Context about the error condition
          example: '{missingScopes=[scope1, scope2]}'
        in:
          type: string
          description: The name of the field or parameter in which the error was found.
        message:
          type: string
          description: A human readable message describing the error along with remediation steps where
            appropriate
        subCategory:
          type: string
          description: A specific category that contains more specific detail about the error
      description: Represents detailed information about an error that occurred in the API. This component
        is used to provide additional context and specifics about errors, typically as part of an error
        response.
    ForwardPaging:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/NextPage'
      description: Paging information for forward-only pagination. Contains the next page reference when
        more results are available; omitted or empty on the last page.
    NextPage:
      required:
      - after
      type: object
      properties:
        after:
          type: string
          description: A paging cursor token for retrieving subsequent pages.
        link:
          type: string
          description: A URL that can be used to retrieve the next page results.
      description: Specifies the paging information needed to retrieve the next set of results in a paginated
        API response
    Paging:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/NextPage'
        prev:
          $ref: '#/components/schemas/PreviousPage'
    PreviousPage:
      required:
      - before
      type: object
      properties:
        before:
          type: string
          description: A paging cursor token for retrieving previous pages.
        link:
          type: string
          description: A URL that can be used to retrieve the previous pages' results.
      description: specifies the paging information needed to retrieve the previous set of results in
        a paginated API response
    PublicObjectWarning:
      required:
      - category
      - context
      - message
      type: object
      properties:
        category:
          type: string
        context:
          type: object
          additionalProperties:
            type: string
        message:
          type: string
    SimplePublicObject:
      required:
      - archived
      - createdAt
      - id
      - properties
      - updatedAt
      type: object
      properties:
        archived:
          type: boolean
          description: Whether the object is archived.
        archivedAt:
          type: string
          description: The timestamp when the object was archived, in ISO 8601 format.
          format: date-time
        createdAt:
          type: string
          description: The timestamp when the object was created, in ISO 8601 format.
          format: date-time
        id:
          type: string
          description: The unique ID of the object.
        objectWriteTraceId:
          type: string
          description: An identifier used for tracing the write request for the object.
        properties:
          type: object
          additionalProperties:
            type: string
          description: Key-value pairs representing the properties of the object.
        propertiesWithHistory:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/ValueWithTimestamp'
          description: Key-value pairs representing the properties of the object along with their history.
        updatedAt:
          type: string
          description: The timestamp when the object was last updated, in ISO 8601 format.
          format: date-time
        url:
          type: string
          description: The URL associated with the object.
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/PublicObjectWarning'
      description: A simple public object.
    SimplePublicObjectId:
      required:
      - id
      type: object
      properties:
        id:
          type: string
          description: The unique ID of the object.
          example: '430001'
      description: Contains the Id of a Public Object
    SimplePublicObjectWithAssociations:
      required:
      - archived
      - createdAt
      - id
      - properties
      - updatedAt
      type: object
      properties:
        archived:
          type: boolean
          description: Whether the object is archived.
        archivedAt:
          type: string
          description: The timestamp when the object was archived, in ISO 8601 format.
          format: date-time
        associations:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/CollectionResponseAssociatedId'
          description: A list defining relationships with other objects.
        createdAt:
          type: string
          description: The timestamp when the object was created, in ISO 8601 format.
          format: date-time
        id:
          type: string
          description: The unique ID of the object.
        objectWriteTraceId:
          type: string
          description: An identifier used for tracing the creation or update request of the object.
        properties:
          type: object
          additionalProperties:
            type: string
          description: Key value pairs representing the properties of the object.
        propertiesWithHistory:
          type: object
          additionalProperties:
            type: array
            items:
              $ref: '#/components/schemas/ValueWithTimestamp'
          description: Key-value pairs representing the properties of the object along with their history.
        updatedAt:
          type: string
          description: The timestamp when the object was last updated, in ISO 8601 format.
          format: date-time
        url:
          type: string
          description: The URL on the API that provide direct navigation to the corresponding UI pages
            for the connectors.
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/PublicObjectWarning'
      description: Represents a CRM object along with its properties, timestamps, and a set of associated
        object IDs grouped by association type.
    StandardError:
      required:
      - category
      - context
      - errors
      - links
      - message
      - status
      type: object
      properties:
        category:
          type: string
          description: The main category of the error.
        context:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
          description: Additional context-specific information related to the error.
        errors:
          type: array
          description: The detailed error objects.
          items:
            $ref: '#/components/schemas/ErrorDetail'
        id:
          type: string
          description: A unique ID for the error instance.
        links:
          type: object
          additionalProperties:
            type: string
          description: URLs linking to documentation or resources associated with the error.
        message:
          type: string
          description: A human-readable string describing the error and possible remediation steps.
        status:
          type: string
          description: The HTTP status code associated with the error.
        subCategory:
          type: object
          properties: {}
          description: A more specific error category within each main category.
      description: Represents a standard error response in the HubSpot API, providing detailed information
        about an error that occurred during an API request.
    ValueWithTimestamp:
      required:
      - sourceType
      - timestamp
      - value
      type: object
      properties:
        sourceId:
          type: string
          description: The unique ID of the property.
        sourceLabel:
          type: string
          description: A human-readable label.
        sourceType:
          type: string
          description: The property type.
        timestamp:
          type: string
          description: The timestamp when the property was updated, in ISO 8601 format.
          format: date-time
        updatedByUserId:
          type: integer
          description: The ID of the user who last updated the property.
          format: int32
        value:
          type: string
          description: The property value.
      description: Property model that includes timestamp.
  responses:
    Error:
      description: An error occurred.
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    developer_hapikey:
      type: apiKey
      name: hapikey
      in: query
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hubspot.com/oauth/authorize
          tokenUrl: https://api.hubapi.com/oauth/v1/token
          scopes:
            crm.objects.commercepayments.read: ''
            crm.objects.contracts.read: ''
            oauth: ''
            oauth-access: ''
    private_apps:
      type: apiKey
      name: private-app
      in: header
    private_apps_legacy:
      type: apiKey
      name: private-app-legacy
      in: header
x-hubspot-product-tier-requirements:
  marketing: FREE
  sales: FREE
  service: FREE
  cms: FREE
  commerce: FREE
  crmHub: FREE
  dataHub: FREE