HubSpot Companies API

openapi: 3.1.0
info:
  title: HubSpot CRM Companies API
  description: >-
    Company records store data about businesses and organizations. The companies
    endpoints allow you to manage this data and sync it between HubSpot and
    other systems, including creating, retrieving, updating, and deleting company
    records and managing their associations.
  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 company associations
- name: Batch
  description: Batch operations for companies
- name: Companies
  description: Operations for managing company records
paths:
  /crm/v3/objects/companies:
    get:
      operationId: listCompanies
      summary: Hubspot List Companies
      description: >-
        Returns a page of company records. Use the limit and after parameters
        to paginate through companies. You can also specify which properties
        to return using the properties parameter.
      tags:
      - Companies
      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 companies.
        schema:
          type: boolean
          default: false
        example: false
      responses:
        '200':
          description: Successful response with a list of companies.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseCompany'
              examples:
                Listcompanies200Example:
                  summary: Default listCompanies 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: createCompany
      summary: Hubspot Create a Company
      description: >-
        Creates a new company record with the provided properties. The request
        body should include a properties object containing the field values
        for the company you want to create.
      tags:
      - Companies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimplePublicObjectInput'
            examples:
              CreatecompanyRequestExample:
                summary: Default createCompany request
                x-microcks-default: true
                value:
                  properties: &id003
                    key: value
      responses:
        '201':
          description: Company created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
              examples:
                Createcompany201Example:
                  summary: Default createCompany 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/companies/{companyId}:
    get:
      operationId: getCompany
      summary: Hubspot Get a Company
      description: >-
        Returns a single company record by its ID. You can specify which
        properties to return using the properties parameter.
      tags:
      - Companies
      parameters:
      - name: companyId
        in: path
        required: true
        description: The ID of the company 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 companies.
        schema:
          type: boolean
          default: false
        example: false
      responses:
        '200':
          description: Successful response with the company record.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
              examples:
                Getcompany200Example:
                  summary: Default getCompany 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: updateCompany
      summary: Hubspot Update a Company
      description: >-
        Performs a partial update of a company record. Only the properties
        included in the request body will be updated; other properties will
        remain unchanged.
      tags:
      - Companies
      parameters:
      - name: companyId
        in: path
        required: true
        description: The ID of the company to update.
        schema:
          type: string
        example: '500123'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SimplePublicObjectInput'
            examples:
              UpdatecompanyRequestExample:
                summary: Default updateCompany request
                x-microcks-default: true
                value:
                  properties: *id003
      responses:
        '200':
          description: Company updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Company'
              examples:
                Updatecompany200Example:
                  summary: Default updateCompany 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: deleteCompany
      summary: Hubspot Archive a Company
      description: >-
        Archives (soft deletes) a company record by its ID. Archived companies
        can be restored using the HubSpot UI or API. This does not permanently
        delete the company from HubSpot.
      tags:
      - Companies
      parameters:
      - name: companyId
        in: path
        required: true
        description: The ID of the company to archive.
        schema:
          type: string
        example: '500123'
      responses:
        '204':
          description: Company archived successfully.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /crm/v3/objects/companies/batch/read:
    post:
      operationId: batchReadCompanies
      summary: Hubspot Batch Read Companies
      description: >-
        Reads a batch of company records by their IDs or unique property values.
        Useful for retrieving multiple companies in a single API call instead
        of making individual requests.
      tags:
      - Batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchReadInput'
            examples:
              BatchreadcompaniesRequestExample:
                summary: Default batchReadCompanies 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/BatchResponseCompany'
              examples:
                Batchreadcompanies200Example:
                  summary: Default batchReadCompanies 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/companies/batch/create:
    post:
      operationId: batchCreateCompanies
      summary: Hubspot Batch Create Companies
      description: >-
        Creates multiple company records in a single API call. The request
        body should include an array of company property objects.
      tags:
      - Batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchCreateInput'
            examples:
              BatchcreatecompaniesRequestExample:
                summary: Default batchCreateCompanies request
                x-microcks-default: true
                value:
                  inputs: &id008
                  - properties: *id003
      responses:
        '201':
          description: Companies created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponseCompany'
              examples:
                Batchcreatecompanies201Example:
                  summary: Default batchCreateCompanies 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/companies/batch/update:
    post:
      operationId: batchUpdateCompanies
      summary: Hubspot Batch Update Companies
      description: >-
        Updates multiple company records in a single API call. Each record
        in the request must include the company ID and the properties to update.
      tags:
      - Batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchUpdateInput'
            examples:
              BatchupdatecompaniesRequestExample:
                summary: Default batchUpdateCompanies request
                x-microcks-default: true
                value:
                  inputs: &id009
                  - id: '500123'
                    properties:
                      key: value
      responses:
        '200':
          description: Companies updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BatchResponseCompany'
              examples:
                Batchupdatecompanies200Example:
                  summary: Default batchUpdateCompanies 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/companies/batch/archive:
    post:
      operationId: batchArchiveCompanies
      summary: Hubspot Batch Archive Companies
      description: >-
        Archives multiple company records in a single API call by their IDs.
        Archived companies can be restored using the HubSpot UI or API.
      tags:
      - Batch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BatchArchiveInput'
            examples:
              BatcharchivecompaniesRequestExample:
                summary: Default batchArchiveCompanies request
                x-microcks-default: true
                value:
                  inputs: &id010
                  - id: '500123'
      responses:
        '204':
          description: Companies archived successfully.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /crm/v3/objects/companies/search:
    post:
      operationId: searchCompanies
      summary: Hubspot Search Companies
      description: >-
        Searches for company records using filter groups, sorts, and other
        query parameters. Supports complex filtering with multiple filter
        groups and operators for precise record retrieval.
      tags:
      - Companies
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SearchRequest'
            examples:
              SearchcompaniesRequestExample:
                summary: Default searchCompanies 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/CollectionResponseCompany'
              examples:
                Searchcompanies200Example:
                  summary: Default searchCompanies 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/companies/{companyId}/associations/{toObjectType}:
    get:
      operationId: listCompanyAssociations
      summary: Hubspot List Company Associations
      description: >-
        Returns all associations of a company record to objects of a specified
        type, such as contacts, deals, or tickets.
      tags:
      - Associations
      parameters:
      - name: companyId
        in: path
        required: true
        description: The ID of the company.
        schema:
          type: string
        example: '500123'
      - name: toObjectType
        in: path
        required: true
        description: The type of associated object (e.g., contacts, deals, tickets).
        schema:
          type: string
        example: standard
      responses:
        '200':
          description: List of associations returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseAssociation'
              examples:
                Listcompanyassociations200Example:
                  summary: Default listCompanyAssociations 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/companies/{companyId}/associations/{toObjectType}/{toObjectId}/{associationType}:
    put:
      operationId: createCompanyAssociation
      summary: Hubspot Create a Company Association
      description: >-
        Creates an association between a company and another CRM object record.
        The association type specifies the relationship between the objects.
      tags:
      - Associations
      parameters:
      - name: companyId
        in: path
        required: true
        description: The ID of the company.
        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:
                Createcompanyassociation200Example:
                  summary: Default createCompanyAssociation 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: deleteCompanyAssociation
      summary: Hubspot Delete a Company Association
      description: >-
        Removes an association between a company and another CRM object record.
        This does not delete the company or the associated object, only the
        relationship between them.
      tags:
      - Associations
      parameters:
      - name: companyId
        in: path
        required: true
        description: The ID of the company.
        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:
    Company:
      type: object
      description: A HubSpot company record.
      properties:
        id:
          type: string
          description: The unique identifier for the company.
          example: '500123'
        properties:
          type: object
          description: The company's properties as key-value pairs.
          additionalProperties:
            type: string
          example: *id001
        createdAt:
          type: string
          format: date-time
          description: The date and time the company was created.
          example: '2025-03-15T14:30:00Z'
        updatedAt:
          type: string
          format: date-time
          description: The date and time the company was last updated.
          example: '2025-03-15T14:30:00Z'
        archived:
          type: boolean
          description: Whether the company has been archived.
          example: true
        associations:
          type: object
          description: The company's associations with other CRM objects.
          additionalProperties:
            $ref: '#/components/schemas/CollectionResponseAssociation'
          example: *id002
    CollectionResponseCompany:
      type: object
      description: A paginated list of company records.
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/Company'
          example: *id005
        paging:
          $ref: '#/components/schemas/Paging'
    BatchResponseCompany:
      type: object
      description: Results from a batch operation on companies.
      properties:
        status:
          type: string
          example: active
        results:
          type: array
          items:
            $ref: '#/components/schemas/Company'
          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
          description: The properties to set on the 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'