> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.fr/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Search records

> **Supported products**

> **Required Scopes**


## OpenAPI

````yaml specs/2026-09/crm-objects-v2026-09.json POST /crm/objects/2026-09/{objectType}/search
openapi: 3.0.1
info:
  title: CRM Objects
  description: Basepom for all HubSpot Projects
  version: 2026-09
  x-hubspot-product-tier-requirements:
    marketing: FREE
    sales: FREE
    service: FREE
    cms: FREE
    commerce: FREE
    crmHub: FREE
    dataHub: FREE
  x-hubspot-api-use-case: >-
    After creating a Cars custom object, you can create a record for each car,
    then associate it with the contact who bought it.
  x-hubspot-introduction: >-
    Use the objects API to create and manage records for an object. The
    endpoints can be used for objects included in all accounts, such as contacts
    and companies, as well as for custom objects in Enterprise accounts.
servers:
  - url: https://api.hubapi.com
security: []
tags:
  - name: Basic
  - name: Batch
  - name: Search
paths:
  /crm/objects/2026-09/{objectType}/search:
    post:
      tags:
        - Search
      operationId: >-
        post-/crm/objects/2026-09/{objectType}/search_/crm/objects/2026-03/{objectType}/search
      parameters:
        - name: objectType
          in: path
          description: ''
          required: true
          style: simple
          explode: false
          schema:
            type: string
      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:
          $ref: '#/components/responses/Error'
          description: ''
      security:
        - oauth2:
            - crm.objects.orders.read
        - oauth2:
            - crm.objects.appointments.sensitive.read.v2
        - oauth2:
            - crm.objects.contacts.highly_sensitive.read.v2
        - oauth2:
            - crm.objects.companies.write
        - oauth2:
            - crm.objects.custom.sensitive.read.v2
        - oauth2:
            - crm.objects.users.read
        - oauth2:
            - crm.objects.users.write
        - oauth2:
            - crm.objects.commercepayments.write
        - oauth2:
            - crm.objects.invoices.write
        - oauth2:
            - crm.objects.contacts.highly_sensitive.write.v2
        - oauth2:
            - crm.objects.carts.write
        - oauth2:
            - crm.objects.appointments.write
        - oauth2:
            - crm.objects.partner-services.read
        - oauth2:
            - crm.objects.custom.write
        - oauth2:
            - tickets
        - oauth2:
            - crm.objects.deals.sensitive.write.v2
        - oauth2:
            - oauth
        - oauth2:
            - crm.objects.deals.highly_sensitive.write.v2
        - oauth2:
            - crm.objects.companies.highly_sensitive.write.v2
        - oauth2:
            - tickets.sensitive.v2
        - oauth2:
            - crm.objects.projects.highly_sensitive.read
        - oauth2:
            - crm.objects.appointments.read
        - oauth2:
            - crm.objects.appointments.sensitive.write.v2
        - oauth2:
            - crm.objects.projects.sensitive.read
        - oauth2:
            - crm.objects.projects.write
        - oauth2:
            - media_bridge.read
        - oauth2:
            - crm.objects.listings.read
        - oauth2:
            - crm.objects.courses.write
        - oauth2:
            - crm.objects.carts.read
        - oauth2:
            - crm.objects.listings.write
        - oauth2:
            - crm.objects.custom.read
        - oauth2:
            - crm.objects.deals.read
        - oauth2:
            - crm.objects.subscriptions.read
        - oauth2:
            - crm.objects.companies.sensitive.read.v2
        - oauth2:
            - crm.objects.companies.read
        - oauth2:
            - crm.objects.custom.sensitive.write.v2
        - oauth2:
            - crm.objects.deals.highly_sensitive.read.v2
        - oauth2:
            - crm.objects.contacts.sensitive.write.v2
        - oauth2:
            - crm.objects.companies.highly_sensitive.read.v2
        - oauth2:
            - crm.objects.projects.highly_sensitive.write
        - oauth2:
            - crm.objects.partner-services.write
        - oauth2:
            - crm.objects.contacts.read
        - oauth2:
            - crm.objects.services.write
        - oauth2:
            - crm.objects.orders.write
        - oauth2:
            - crm.objects.subscriptions.write
        - oauth2:
            - crm.objects.commercepayments.read
        - oauth2:
            - crm.objects.products.write
        - oauth2:
            - crm.objects.custom.highly_sensitive.read.v2
        - oauth2:
            - crm.objects.deals.write
        - oauth2:
            - crm.objects.invoices.read
        - oauth2:
            - e-commerce
        - oauth2:
            - tickets.highly_sensitive.v2
        - oauth2:
            - crm.objects.quotes.write
        - oauth2:
            - crm.objects.leads.read
        - oauth2:
            - crm.objects.leads.write
        - oauth2:
            - crm.objects.custom.highly_sensitive.write.v2
        - oauth2:
            - crm.objects.projects.sensitive.write
        - oauth2:
            - crm.objects.deals.sensitive.read.v2
        - oauth2:
            - crm.objects.goals.write
        - oauth2:
            - crm.objects.companies.sensitive.write.v2
        - oauth2:
            - crm.objects.projects.read
        - oauth2:
            - crm.objects.contacts.write
        - oauth2:
            - crm.objects.goals.read
        - oauth2:
            - crm.objects.partner-clients.write
        - oauth2:
            - crm.objects.line_items.read
        - oauth2:
            - crm.objects.contacts.sensitive.read.v2
        - oauth2:
            - crm.objects.line_items.write
        - oauth2:
            - crm.objects.products.read
        - oauth2:
            - crm.objects.courses.read
        - oauth2:
            - crm.objects.quotes.read
        - oauth2:
            - crm.objects.partner-clients.read
        - oauth2:
            - crm.objects.services.read
        - private_apps:
            - crm.objects.listings.write
        - private_apps:
            - crm.objects.custom.read
        - private_apps:
            - crm.objects.deals.read
        - private_apps:
            - crm.objects.appointments.sensitive.read.v2
        - private_apps:
            - crm.objects.companies.highly_sensitive.read
        - private_apps:
            - crm.objects.contacts.highly_sensitive.read.v2
        - private_apps:
            - crm.objects.deals.sensitive.write
        - private_apps:
            - crm.objects.companies.write
        - private_apps:
            - crm.objects.contacts.sensitive.write.v2
        - private_apps:
            - crm.objects.users.read
        - private_apps:
            - crm.objects.custom.sensitive.read.v2
        - private_apps:
            - crm.objects.contacts.highly_sensitive.write.v2
        - private_apps:
            - crm.objects.deals.highly_sensitive.read.v2
        - private_apps:
            - crm.objects.commercepayments.write
        - private_apps:
            - tickets.highly_sensitive
        - private_apps:
            - crm.objects.companies.highly_sensitive.read.v2
        - private_apps:
            - crm.objects.partner-services.read
        - private_apps:
            - crm.objects.projects.highly_sensitive.write
        - private_apps:
            - crm.objects.custom.highly_sensitive.write
        - private_apps:
            - crm.objects.deals.sensitive.read
        - private_apps:
            - crm.objects.partner-services.write
        - private_apps:
            - crm.objects.appointments.sensitive.write
        - private_apps:
            - tickets
        - private_apps:
            - crm.objects.deals.sensitive.write.v2
        - private_apps:
            - crm.objects.companies.highly_sensitive.write
        - private_apps:
            - tickets.sensitive
        - private_apps:
            - crm.objects.commercepayments.read
        - private_apps:
            - crm.objects.appointments.sensitive.read
        - private_apps:
            - crm.objects.custom.highly_sensitive.read.v2
        - private_apps:
            - crm.objects.companies.sensitive.write
        - private_apps:
            - tickets.sensitive.v2
        - private_apps:
            - e-commerce
        - private_apps:
            - crm.objects.deals.write
        - private_apps:
            - crm.objects.appointments.read
        - private_apps:
            - crm.objects.custom.highly_sensitive.read
        - private_apps:
            - crm.objects.projects.highly_sensitive.read
        - private_apps:
            - crm.objects.leads.write
        - private_apps:
            - tickets.highly_sensitive.v2
        - private_apps:
            - crm.objects.quotes.write
        - private_apps:
            - crm.objects.projects.sensitive.read
        - private_apps:
            - crm.objects.goals.write
        - private_apps:
            - crm.objects.contacts.highly_sensitive.read
        - private_apps:
            - crm.objects.courses.write
        - private_apps:
            - crm.objects.partner-clients.write
        - private_apps:
            - crm.objects.line_items.read
        - private_apps:
            - crm.objects.companies.sensitive.write.v2
        - private_apps:
            - crm.objects.projects.read
        - private_apps:
            - media_bridge.read
        - private_apps:
            - crm.objects.line_items.write
        - private_apps:
            - crm.objects.contacts.sensitive.read.v2
        - private_apps:
            - crm.objects.custom.sensitive.write
        - private_apps:
            - crm.objects.contacts.sensitive.read
        - private_apps:
            - crm.objects.carts.read
        - private_apps:
            - crm.objects.partner-clients.read
        - private_apps:
            - crm.objects.quotes.read
        - private_apps:
            - crm.objects.services.read
        - private_apps:
            - crm.objects.orders.read
        - private_apps:
            - crm.objects.appointments.write
        - private_apps:
            - crm.objects.subscriptions.read
        - private_apps:
            - crm.objects.contacts.sensitive.write
        - private_apps:
            - crm.objects.companies.sensitive.read.v2
        - private_apps:
            - crm.objects.companies.read
        - private_apps:
            - crm.objects.companies.sensitive.read
        - private_apps:
            - crm.objects.custom.sensitive.write.v2
        - private_apps:
            - crm.objects.users.write
        - private_apps:
            - crm.objects.invoices.write
        - private_apps:
            - crm.objects.deals.highly_sensitive.read
        - private_apps:
            - crm.objects.carts.write
        - private_apps:
            - crm.objects.orders.write
        - private_apps:
            - crm.objects.services.write
        - private_apps:
            - crm.objects.subscriptions.write
        - private_apps:
            - crm.objects.contacts.read
        - private_apps:
            - crm.objects.custom.write
        - private_apps:
            - crm.objects.deals.highly_sensitive.write.v2
        - private_apps:
            - crm.objects.companies.highly_sensitive.write.v2
        - private_apps:
            - crm.objects.products.write
        - private_apps:
            - crm.objects.appointments.sensitive.write.v2
        - private_apps:
            - crm.objects.invoices.read
        - private_apps:
            - oauth
        - private_apps:
            - crm.objects.deals.sensitive.read.v2
        - private_apps:
            - crm.objects.projects.sensitive.write
        - private_apps:
            - crm.objects.projects.write
        - private_apps:
            - crm.objects.custom.highly_sensitive.write.v2
        - private_apps:
            - crm.objects.goals.read
        - private_apps:
            - crm.objects.contacts.write
        - private_apps:
            - crm.objects.leads.read
        - private_apps:
            - crm.objects.custom.sensitive.read
        - private_apps:
            - crm.objects.contacts.highly_sensitive.write
        - private_apps:
            - crm.objects.products.read
        - private_apps:
            - crm.objects.listings.read
        - private_apps:
            - crm.objects.courses.read
        - private_apps:
            - crm.objects.deals.highly_sensitive.write
        - private_apps_legacy:
            - contacts
components:
  schemas:
    PublicObjectSearchRequest:
      required:
        - after
        - filterGroups
        - limit
        - properties
        - sorts
      type: object
      properties:
        after:
          type: string
          description: A paging cursor token for retrieving subsequent pages.
        filterGroups:
          type: array
          description: Up to 6 groups of filters defining additional query criteria.
          items:
            $ref: '#/components/schemas/FilterGroup'
        limit:
          type: integer
          description: The maximum results to return, up to 200 objects.
          format: int32
        properties:
          type: array
          description: A list of property names to include in the response.
          items:
            type: string
        query:
          type: string
          description: The search query string, up to 3000 characters.
        sorts:
          type: array
          description: Specifies sorting order based on object properties.
          items:
            type: string
      description: Describes a search request
    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 total number of objects included into response.
          format: int32
      description: >-
        Represents a list of simple objects returned from an API request, along
        with the total count of objects available.
    FilterGroup:
      required:
        - filters
      type: object
      properties:
        filters:
          type: array
          items:
            $ref: '#/components/schemas/Filter'
    Paging:
      type: object
      properties:
        next:
          $ref: '#/components/schemas/NextPage'
        prev:
          $ref: '#/components/schemas/PreviousPage'
    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
            nullable: true
          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: Direct URL for this object in the portal
      description: A simple public object.
    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
      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
    Filter:
      required:
        - operator
        - propertyName
      type: object
      properties:
        highValue:
          type: string
          description: The upper boundary value when using ranged-based filters.
        operator:
          type: string
          description: 'null'
          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. 
    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
    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
    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.
    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: The context for the error.
          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
  responses:
    Error:
      description: An error occurred.
      content:
        '*/*':
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://app.hubspot.com/oauth/authorize
          tokenUrl: https://api.hubapi.com/oauth/v1/token
          scopes:
            crm.objects.appointments.read: Read appointments
            crm.objects.appointments.sensitive.read.v2: Read appointments (sensitive)
            crm.objects.appointments.sensitive.write.v2: Write appointments (sensitive)
            crm.objects.appointments.write: Write appointments
            crm.objects.carts.read: Read carts
            crm.objects.carts.write: Write cart
            crm.objects.commercepayments.read: Read commerce payments
            crm.objects.commercepayments.write: Write commerce payments
            crm.objects.companies.highly_sensitive.read.v2: View company records (highly-sensitive)
            crm.objects.companies.highly_sensitive.write.v2: Change company records (highly-sensitive)
            crm.objects.companies.read: Create or update company records
            crm.objects.companies.sensitive.read.v2: View sensitive properties on company records
            crm.objects.companies.sensitive.write.v2: Create or update sensitive properties on company records
            crm.objects.companies.write: View company records
            crm.objects.contacts.highly_sensitive.read.v2: View contact records (highly-sensitive)
            crm.objects.contacts.highly_sensitive.write.v2: Change contact records (highly-sensitive)
            crm.objects.contacts.read: View contact records
            crm.objects.contacts.sensitive.read.v2: View sensitive properties on contact records
            crm.objects.contacts.sensitive.write.v2: Create or update sensitive properties on contact records
            crm.objects.contacts.write: Create or update contact records
            crm.objects.courses.read: Read courses
            crm.objects.courses.write: Write courses
            crm.objects.custom.highly_sensitive.read.v2: View custom object records (highly-sensitive)
            crm.objects.custom.highly_sensitive.write.v2: Change custom object records (highly-sensitive)
            crm.objects.custom.read: View custom object records
            crm.objects.custom.sensitive.read.v2: View custom object records (sensitive)
            crm.objects.custom.sensitive.write.v2: Change custom object records (sensitive)
            crm.objects.custom.write: Change custom object records
            crm.objects.deals.highly_sensitive.read.v2: View deal records (highly-sensitive)
            crm.objects.deals.highly_sensitive.write.v2: Change deal records (highly-sensitive)
            crm.objects.deals.read: View deal records
            crm.objects.deals.sensitive.read.v2: View sensitive properties on deal records
            crm.objects.deals.sensitive.write.v2: Create or update sensitive properties on deal records
            crm.objects.deals.write: Create or update deal records
            crm.objects.goals.read: Read access to goals
            crm.objects.goals.write: Create and update goals
            crm.objects.invoices.read: Read invoices
            crm.objects.invoices.write: Write invoices
            crm.objects.leads.read: Read lead objects
            crm.objects.leads.write: Modify lead objects
            crm.objects.line_items.read: Line Items
            crm.objects.line_items.write: Line Items
            crm.objects.listings.read: Read listings
            crm.objects.listings.write: Write listings
            crm.objects.orders.read: Read Orders
            crm.objects.orders.write: Write orders
            crm.objects.partner-clients.read: View Partner Client CRM objects
            crm.objects.partner-clients.write: Edit Partner Client CRM objects
            crm.objects.partner-services.read: View Partner Service CRM objects
            crm.objects.partner-services.write: Edit Partner Service CRM objects
            crm.objects.products.read: Read products in Products Library
            crm.objects.products.write: Write products in Products Library
            crm.objects.projects.highly_sensitive.read: Read projects (highly-sensitive)
            crm.objects.projects.highly_sensitive.write: Write projects (highly-sensitive)
            crm.objects.projects.read: Read projects
            crm.objects.projects.sensitive.read: Read projects (sensitive)
            crm.objects.projects.sensitive.write: Write projects (sensitive)
            crm.objects.projects.write: Write projects
            crm.objects.quotes.read: Quotes
            crm.objects.quotes.write: Quotes
            crm.objects.services.read: Read services
            crm.objects.services.write: Write services
            crm.objects.subscriptions.read: Read Commerce Subscriptions
            crm.objects.subscriptions.write: Write subscriptions
            crm.objects.users.read: Read User CRM objects
            crm.objects.users.write: Write User CRM objects
            e-commerce: Access to ecommerce
            media_bridge.read: Read media and media events
            oauth: Basic HubSpot account information
            tickets: Tickets
            tickets.highly_sensitive.v2: Tickets (highly-sensitive)
            tickets.sensitive.v2: Tickets (sensitive)
    private_apps:
      type: apiKey
      name: private-app
      in: header
    private_apps_legacy:
      type: apiKey
      name: private-app-legacy
      in: header

````