HubSpot CRM Goal Targets API

openapi: 3.0.1
info:
  title: HubSpot CRM Goal Targets
  description: Basepom for all HubSpot Projects
  version: 2026-03
  x-hubspot-product-tier-requirements:
    marketing: PROFESSIONAL
    sales: STARTER
    service: PROFESSIONAL
    cms: FREE
    commerce: FREE
    crmHub: FREE
    dataHub: FREE
  x-hubspot-api-use-case: Use goals data to create reports for your sales or service team to analyze how
    your reps are performing.
  x-hubspot-introduction: 'Goals in HubSpot are user-specific quotas for their sales and services teams
    based on templates provided by HubSpot. The goals API allows you to retrieve goals data in your HubSpot
    account. '
servers:
- url: https://api.hubapi.com
tags:
- name: Basic
- name: Batch
- name: Search
paths:
  /crm/objects/2026-03/goal_targets:
    get:
      tags:
      - Basic
      summary: Retrieve goal targets
      description: Read a page of goal targets. Control what is returned via the `properties` query param.
      operationId: get-/crm/objects/2026-03/goal_targets_getPage
      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 goal targets
          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.goals.read
      x-hubspot-user-level-auth:
        internalOnly: false
    post:
      tags:
      - Basic
      summary: Create a goal target
      description: Create a goal target with the given properties and return a copy of the object, including
        the ID. Documentation and examples for creating standard goal targets is provided.
      operationId: post-/crm/objects/2026-03/goal_targets_create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimplePublicObjectInputForCreate'
        required: true
      responses:
        '201':
          description: successful operation
          headers:
            Location:
              description: URL of the newly created resource
              style: simple
              explode: false
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimplePublicObject'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.objects.goals.write
      x-hubspot-user-level-auth:
        internalOnly: false
  /crm/objects/2026-03/goal_targets/batch/archive:
    post:
      tags:
      - Batch
      summary: Archive a batch of goal targets by ID
      description: Archive multiple goal targets in a single batch operation using their IDs.
      operationId: post-/crm/objects/2026-03/goal_targets/batch/archive_archive
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchInputSimplePublicObjectId'
        required: true
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.objects.goals.write
      x-hubspot-user-level-auth:
        internalOnly: false
  /crm/objects/2026-03/goal_targets/batch/create:
    post:
      tags:
      - Batch
      summary: Create a batch of goal targets
      description: Create multiple goal targets in a single batch operation.
      operationId: post-/crm/objects/2026-03/goal_targets/batch/create_create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchInputSimplePublicObjectBatchInputForCreate'
        required: true
      responses:
        '201':
          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.goals.write
      x-hubspot-user-level-auth:
        internalOnly: false
  /crm/objects/2026-03/goal_targets/batch/read:
    post:
      tags:
      - Batch
      summary: Read a batch of goal targets 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/goal_targets/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.goals.read
      x-hubspot-user-level-auth:
        internalOnly: false
  /crm/objects/2026-03/goal_targets/batch/update:
    post:
      tags:
      - Batch
      summary: Update a batch of goal targets by internal ID, or unique property values
      description: Update multiple goal targets in a single batch operation using their internal IDs or
        unique property values.
      operationId: post-/crm/objects/2026-03/goal_targets/batch/update_update
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchInputSimplePublicObjectBatchInput'
        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.goals.write
      x-hubspot-user-level-auth:
        internalOnly: false
  /crm/objects/2026-03/goal_targets/batch/upsert:
    post:
      tags:
      - Batch
      summary: Create or update a batch of goal targets by unique property values
      description: Create or update records identified by a unique property value as specified by the
        `idProperty` query param. `idProperty` query param refers to a property whose values are unique
        for the object.
      operationId: post-/crm/objects/2026-03/goal_targets/batch/upsert_upsert
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchInputSimplePublicObjectBatchInputUpsert'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponseSimplePublicUpsertObject'
        '207':
          description: multiple statuses
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponseSimplePublicUpsertObjectWithErrors'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.objects.goals.write
      x-hubspot-user-level-auth:
        internalOnly: false
  /crm/objects/2026-03/goal_targets/search:
    post:
      tags:
      - Search
      summary: Search for goal targets
      description: Search for goal targets using specified criteria.
      operationId: post-/crm/objects/2026-03/goal_targets/search_doSearch
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicObjectSearchRequest'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseWithTotalSimplePublicObject'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.objects.goals.read
      x-hubspot-rate-limit-exemptions:
      - ten-secondly
      x-hubspot-user-level-auth:
        internalOnly: false
  /crm/objects/2026-03/goal_targets/{goalTargetId}:
    get:
      tags:
      - Basic
      summary: Retrieve a goal target
      description: Read an Object identified by `{goalTargetId}`. `{goalTargetId}` 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/goal_targets/{goalTargetId}_getById
      parameters:
      - name: goalTargetId
        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.goals.read
      x-hubspot-user-level-auth:
        internalOnly: false
    delete:
      tags:
      - Basic
      summary: Delete a goal target
      description: Move an Object identified by `{goalTargetId}` to the recycling bin.
      operationId: delete-/crm/objects/2026-03/goal_targets/{goalTargetId}_archive
      parameters:
      - name: goalTargetId
        in: path
        required: true
        schema:
          pattern: .+
          type: string
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.objects.goals.write
      x-hubspot-user-level-auth:
        internalOnly: false
    patch:
      tags:
      - Basic
      summary: Update a goal target
      description: Perform a partial update of an Object identified by `{goalTargetId}`or optionally a
        unique property value as specified by the `idProperty` query param. `{goalTargetId}` refers to
        the internal object ID by default, and the `idProperty` query param refers to a property whose
        values are unique for the object. Provided property values will be overwritten. Read-only and
        non-existent properties will result in an error. Properties values can be cleared by passing an
        empty string.
      operationId: patch-/crm/objects/2026-03/goal_targets/{goalTargetId}_update
      parameters:
      - name: goalTargetId
        in: path
        required: true
        schema:
          pattern: .+
          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
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimplePublicObjectInput'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SimplePublicObject'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.objects.goals.write
      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
    AssociationSpec:
      required:
      - associationCategory
      - associationTypeId
      type: object
      properties:
        associationCategory:
          type: string
          description: The category of the association, such as "HUBSPOT_DEFINED".
          enum:
          - HUBSPOT_DEFINED
          - INTEGRATOR_DEFINED
          - USER_DEFINED
          - WORK
        associationTypeId:
          type: integer
          description: The ID representing the specific type of association.
          format: int32
      description: Defines the type, direction, and details of the relationship between two CRM objects.
    BatchInputSimplePublicObjectBatchInput:
      required:
      - inputs
      type: object
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/SimplePublicObjectBatchInput'
    BatchInputSimplePublicObjectBatchInputForCreate:
      required:
      - inputs
      type: object
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/SimplePublicObjectBatchInputForCreate'
    BatchInputSimplePublicObjectBatchInputUpsert:
      required:
      - inputs
      type: object
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/SimplePublicObjectBatchInputUpsert'
    BatchInputSimplePublicObjectId:
      required:
      - inputs
      type: object
      properties:
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/SimplePublicObjectId'
    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.
    BatchResponseSimplePublicUpsertObject:
      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
        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 process was initiated, in ISO 8601 format.
          format: date-time
        results:
          type: array
          items:
            $ref: '#/components/schemas/SimplePublicUpsertObject'
        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. Can be: "PENDING", "PROCESSING", "CANCELED",
            or "COMPLETE".'
          enum:
          - CANCELED
          - COMPLETE
          - PENDING
          - PROCESSING
      description: Represents the result of a batch upsert operation, including the operation’s status,
        timestamps, and a list of successfully created or updated objects.
    BatchResponseSimplePublicUpsertObjectWithErrors:
      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/SimplePublicUpsertObject'
        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. Can be: "PENDING", "PROCESSING", "CANCELLED",
            or "COMPLETE".'
          enum:
          - CANCELED
          - COMPLETE
          - PENDING
          - PROCESSING
      description: Represents the response from a batch upsert operation, including the status, timestamps,
        successfully processed objects, and any errors that occurred during processing.
    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'
    CollectionResponseWithTotalSimplePublicObject:
      required:
      - results
      - total
      type: object
      properties:
        paging:
          $ref: '#/components/schemas/Paging'
        results:
          type: array
          items:
            $ref: '#/components/schemas/SimplePublicObject'
        total:
          type: integer
          description: The number of available results
          format: int32
      description: Represents a list of simple objects returned from an API request, along with the total
        count of objects available.
    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.
    Filter:
      required:
      - operator
      - propertyName
      type: object
      properties:
        highValue:
          type: string
          description: The upper boundary value when using ranged-based filters.
        operator:
          type: string
          description: The comparison operator used in the filter, such as "EQ" or "GT".
          enum:
          - BETWEEN
          - CONTAINS_TOKEN
          - EQ
          - GT
          - GTE
          - HAS_PROPERTY
          - IN
          - LT
          - LTE
          - NEQ
          - NOT_CONTAINS_TOKEN
          - NOT_HAS_PROPERTY
          - NOT_IN
        propertyName:
          type: string
          description: The name of the property to apply the filter to.
        value:
          type: string
          description: The value to match against the property.
        values:
          type: array
          description: The values to match against the property.
          items:
            type: string
      description: 'Defines a single condition for searching CRM objects, specifying the property to filter
        on, the operator to use (such as equals, greater than, or contains), and the value(s) to compare
        against. '
    FilterGroup:
      required:
      - filters
      type: object
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/Filter'
    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:
     

# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/hubspot/refs/heads/main/openapi/hubspot-crm-goal-targets-api-openapi.yml