HubSpot CRM Schemas API

openapi: 3.0.1
info:
  title: HubSpot CRM Schemas
  description: Basepom for all HubSpot Projects
  version: 2026-09
  x-hubspot-product-tier-requirements:
    marketing: ENTERPRISE
    sales: ENTERPRISE
    service: ENTERPRISE
    cms: ENTERPRISE
    commerce: ENTERPRISE
    crmHub: ENTERPRISE
    dataHub: ENTERPRISE
  x-hubspot-api-use-case: Create a new object for storing information about cars at a car dealership.
    Your object definition could include properties to store information as well as the filters available
    on the custom object index page.
  x-hubspot-introduction: Use the custom objects schema API to define new types of CRM records in your
    account. After setting up an object schema, you'll then be able to create records for that custom
    object both in HubSpot and using the objects API.
servers:
- url: https://api.hubapi.com
tags:
- name: Advanced
- name: Basic
- name: Batch
paths:
  /crm-object-schemas/2026-09/schemas:
    get:
      tags:
      - Basic
      summary: Retrieve all custom object schemas.
      description: Retrieve all custom object schemas, with options to include property definitions, association
        definitions, and audit metadata.
      operationId: get-/crm-object-schemas/2026-09/schemas_getAll
      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
      - name: includeAssociationDefinitions
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: true
      - name: includeAuditMetadata
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: true
      - name: includePropertyDefinitions
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseObjectSchemaNoPaging'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.schemas.custom.read
      - oauth2:
        - crm.objects.custom.sensitive.read.v2
      - oauth2:
        - crm.objects.custom.highly_sensitive.read.v2
      - oauth2:
        - crm.objects.custom.read
      x-hubspot-user-level-auth:
        internalOnly: false
    post:
      tags:
      - Basic
      summary: Create a new custom object schema.
      description: Create a new custom object schema by defining its properties and associations.
      operationId: post-/crm-object-schemas/2026-09/schemas_create
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObjectSchemaEgg'
        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/ObjectSchema'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.schemas.custom.write
      x-hubspot-user-level-auth:
        internalOnly: false
  /crm-object-schemas/2026-09/schemas/batch/read:
    post:
      tags:
      - Batch
      summary: Retrieve multiple custom object schemas in a batch request.
      description: Retrieve details of multiple custom object schemas by providing a batch request with
        specified inputs. This operation allows you to fetch schema information, including properties
        and associations, for multiple custom objects in a single API call.
      operationId: post-/crm-object-schemas/2026-09/schemas/batch/read_/crm-object-schemas/v3/schemas/batch/read
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObjectSchemaBatchReadRequest'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionResponseObjectSchemaNoPaging'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.schemas.custom.read
      - oauth2:
        - crm.objects.custom.sensitive.read.v2
      - oauth2:
        - crm.objects.custom.highly_sensitive.read.v2
      - oauth2:
        - crm.objects.custom.read
      - oauth2:
        - oauth-access
      x-hubspot-user-level-auth:
        internalOnly: false
  /crm-object-schemas/2026-09/schemas/{objectType}:
    get:
      tags:
      - Basic
      summary: Retrieve the schema of a specified custom object.
      description: Retrieve details of a custom object schema, including its properties and associations,
        using the object type ID or fully qualified name.
      operationId: get-/crm-object-schemas/2026-09/schemas/{objectType}_getById
      parameters:
      - name: objectType
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: includeAssociationDefinitions
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: true
      - name: includeAuditMetadata
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: true
      - name: includePropertyDefinitions
        in: query
        description: ''
        required: false
        style: form
        explode: true
        schema:
          type: boolean
          default: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectSchema'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.schemas.custom.read
      - oauth2:
        - crm.objects.custom.sensitive.read.v2
      - oauth2:
        - crm.objects.custom.highly_sensitive.read.v2
      - oauth2:
        - crm.objects.custom.read
      - oauth2:
        - oauth-access
      x-hubspot-user-level-auth:
        internalOnly: false
    delete:
      tags:
      - Basic
      summary: Delete the schema of a specified custom object.
      description: Remove a custom object schema from the account using its object type ID or fully qualified
        name.
      operationId: delete-/crm-object-schemas/2026-09/schemas/{objectType}_archive
      parameters:
      - name: objectType
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        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
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.schemas.custom.write
    patch:
      tags:
      - Basic
      summary: Update the schema of a specified custom object.
      description: Update attributes of a custom object schema, such as properties and labels, using the
        object type ID or fully qualified name.
      operationId: patch-/crm-object-schemas/2026-09/schemas/{objectType}_update
      parameters:
      - name: objectType
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ObjectTypeDefinitionPatch'
        required: true
      responses:
        '200':
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ObjectTypeDefinition'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.schemas.custom.write
      x-hubspot-user-level-auth:
        internalOnly: false
  /crm-object-schemas/2026-09/schemas/{objectType}/associations:
    post:
      tags:
      - Advanced
      summary: Create an association for a specified object type.
      description: Create a new association between the specified object type and another object type.
        This operation requires the definition of the association attributes, such as the primary and
        target object type IDs.
      operationId: post-/crm-object-schemas/2026-09/schemas/{objectType}/associations_createAssociation
      parameters:
      - name: objectType
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssociationDefinitionEgg'
        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/AssociationDefinition'
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.schemas.custom.write
      x-hubspot-user-level-auth:
        internalOnly: false
  /crm-object-schemas/2026-09/schemas/{objectType}/associations/{associationIdentifier}:
    delete:
      tags:
      - Basic
      summary: Delete an existing association for a specified object type.
      description: Remove an association between two object types identified by the association identifier
        and object type. This operation is irreversible and will permanently delete the specified association.
      operationId: delete-/crm-object-schemas/2026-09/schemas/{objectType}/associations/{associationIdentifier}_archiveAssociation
      parameters:
      - name: associationIdentifier
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      - name: objectType
        in: path
        description: ''
        required: true
        style: simple
        explode: false
        schema:
          type: string
      responses:
        '204':
          description: No content
          content: {}
        default:
          description: ''
          $ref: '#/components/responses/Error'
      security:
      - oauth2:
        - crm.schemas.custom.write
components:
  schemas:
    AssociationDefinition:
      required:
      - fromObjectTypeId
      - id
      - toObjectTypeId
      type: object
      properties:
        createdAt:
          type: string
          description: When the association was defined.
          format: date-time
        fromObjectTypeId:
          type: string
          description: ID of the primary object type to link from.
        id:
          type: string
          description: A unique ID for this association.
        name:
          type: string
          description: A unique name for this association.
        toObjectTypeId:
          type: string
          description: ID of the target object type ID to link to.
        updatedAt:
          type: string
          description: When the association was last updated.
          format: date-time
      description: The definition of an association
    AssociationDefinitionEgg:
      required:
      - fromObjectTypeId
      - toObjectTypeId
      type: object
      properties:
        fromObjectTypeId:
          type: string
          description: ID of the primary object type to link from.
        name:
          type: string
          description: A unique name for this association.
        toObjectTypeId:
          type: string
          description: ID of the target object type ID to link to.
    CollectionResponseObjectSchemaNoPaging:
      required:
      - results
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/ObjectSchema'
    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.
    ObjectSchema:
      required:
      - allowsSensitiveProperties
      - archived
      - associations
      - fullyQualifiedName
      - id
      - labels
      - name
      - objectTypeId
      - properties
      - requiredProperties
      - searchableProperties
      - secondaryDisplayProperties
      type: object
      properties:
        allowsSensitiveProperties:
          type: boolean
        archived:
          type: boolean
        associations:
          type: array
          description: Associations defined for a given object type.
          items:
            $ref: '#/components/schemas/AssociationDefinition'
        createdAt:
          type: string
          description: When the object schema was created.
          format: date-time
        createdByUserId:
          type: integer
          format: int32
        description:
          type: string
        fullyQualifiedName:
          type: string
          description: An assigned unique ID for the object, including portal ID and object name.
        id:
          type: string
          description: A unique ID for this schema's object type. Will be defined as {meta-type}-{unique
            ID}.
        labels:
          $ref: '#/components/schemas/ObjectTypeDefinitionLabels'
        name:
          type: string
          description: A unique name for the schema's object type.
        objectTypeId:
          type: string
        primaryDisplayProperty:
          type: string
          description: The name of the primary property for this object. This will be displayed as primary
            on the HubSpot record page for this object type.
        properties:
          type: array
          description: Properties defined for this object type.
          items:
            $ref: '#/components/schemas/Property'
        requiredProperties:
          type: array
          description: The names of properties that should be **required** when creating an object of
            this type.
          items:
            type: string
        searchableProperties:
          type: array
          description: Names of properties that will be indexed for this object type in by HubSpot's product
            search.
          items:
            type: string
        secondaryDisplayProperties:
          type: array
          description: The names of secondary properties for this object. These will be displayed as secondary
            on the HubSpot record page for this object type.
          items:
            type: string
        updatedAt:
          type: string
          description: When the object schema was last updated.
          format: date-time
        updatedByUserId:
          type: integer
          format: int32
    ObjectSchemaBatchReadRequest:
      required:
      - includeAssociationDefinitions
      - includeAuditMetadata
      - includePropertyDefinitions
      - inputs
      type: object
      properties:
        includeAssociationDefinitions:
          type: boolean
          description: Indicates whether to include association definitions in the response.
        includeAuditMetadata:
          type: boolean
          description: Indicates whether to include audit metadata in the response.
        includePropertyDefinitions:
          type: boolean
          description: Indicates whether to include property definitions in the response.
        inputs:
          type: array
          items:
            type: string
    ObjectSchemaEgg:
      required:
      - allowsSensitiveProperties
      - associatedObjects
      - labels
      - name
      - properties
      - requiredProperties
      - searchableProperties
      - secondaryDisplayProperties
      - shouldCreateSameObjectAssociation
      type: object
      properties:
        allowsSensitiveProperties:
          type: boolean
          description: Determines if the object type can include properties that are marked as sensitive.
        associatedObjects:
          type: array
          description: Associations defined for this object type.
          items:
            type: string
        description:
          type: string
          description: A brief explanation of the object type.
        labels:
          $ref: '#/components/schemas/ObjectTypeDefinitionLabels'
        name:
          type: string
          description: A unique name for this object. For internal use only.
        primaryDisplayProperty:
          type: string
          description: The name of the primary property for this object. This will be displayed as primary
            on the HubSpot record page for this object type.
        properties:
          type: array
          description: Properties defined for this object type.
          items:
            $ref: '#/components/schemas/ObjectTypePropertyCreate'
        requiredProperties:
          type: array
          description: The names of properties that should be **required** when creating an object of
            this type.
          items:
            type: string
        searchableProperties:
          type: array
          description: Names of properties that will be indexed for this object type in by HubSpot's product
            search.
          items:
            type: string
        secondaryDisplayProperties:
          type: array
          description: The names of secondary properties for this object. These will be displayed as secondary
            on the HubSpot record page for this object type.
          items:
            type: string
        shouldCreateSameObjectAssociation:
          type: boolean
    ObjectTypeDefinition:
      required:
      - allowsSensitiveProperties
      - archived
      - fullyQualifiedName
      - id
      - labels
      - name
      - objectTypeId
      - requiredProperties
      - searchableProperties
      - secondaryDisplayProperties
      type: object
      properties:
        allowsSensitiveProperties:
          type: boolean
          description: Indicates whether the object type allows properties that contain sensitive data.
        archived:
          type: boolean
          description: Indicates whether the object type is archived.
        createdAt:
          type: string
          description: When the object type was created.
          format: date-time
        description:
          type: string
          description: A description of the object type.
        fullyQualifiedName:
          type: string
          description: An assigned unique ID for the object, including portal ID and object name.
        id:
          type: string
          description: A unique ID for this object type. Will be defined as {meta-type}-{unique ID}.
        labels:
          $ref: '#/components/schemas/ObjectTypeDefinitionLabels'
        name:
          type: string
          description: A unique name for this object. For internal use only.
        objectTypeId:
          type: string
          description: A unique identifier for the object type.
        portalId:
          type: integer
          description: The ID of the account that this object type is specific to.
          format: int32
        primaryDisplayProperty:
          type: string
          description: The name of the primary property for this object. This will be displayed as primary
            on the HubSpot record page for this object type.
        requiredProperties:
          type: array
          description: The names of properties that should be **required** when creating an object of
            this type.
          items:
            type: string
        searchableProperties:
          type: array
          description: Names of properties that will be indexed for this object type in by HubSpot's product
            search.
          items:
            type: string
        secondaryDisplayProperties:
          type: array
          description: The names of secondary properties for this object. These will be displayed as secondary
            on the HubSpot record page for this object type.
          items:
            type: string
        updatedAt:
          type: string
          description: When the object type was last updated.
          format: date-time
    ObjectTypeDefinitionLabels:
      type: object
      properties:
        plural:
          type: string
          description: The word for multiple objects. (There’s no way to change this later.)
        singular:
          type: string
          description: The word for one object. (There’s no way to change this later.)
    ObjectTypeDefinitionPatch:
      required:
      - clearDescription
      type: object
      properties:
        allowsSensitiveProperties:
          type: boolean
          description: Determines if the object type can include properties that are marked as sensitive.
        clearDescription:
          type: boolean
          description: Indicates whether the description of the object type should be cleared.
        description:
          type: string
          description: A brief explanation of the object type.
        labels:
          $ref: '#/components/schemas/ObjectTypeDefinitionLabels'
        primaryDisplayProperty:
          type: string
          description: The name of the primary property for this object. This will be displayed as primary
            on the HubSpot record page for this object type.
        requiredProperties:
          type: array
          description: The names of properties that should be **required** when creating an object of
            this type.
          items:
            type: string
        restorable:
          type: boolean
          description: Specifies if the object type can be restored after being deleted.
        searchableProperties:
          type: array
          description: Names of properties that will be indexed for this object type in by HubSpot's product
            search.
          items:
            type: string
        secondaryDisplayProperties:
          type: array
          description: The names of secondary properties for this object. These will be displayed as secondary
            on the HubSpot record page for this object type.
          items:
            type: string
    ObjectTypePropertyCreate:
      required:
      - fieldType
      - label
      - name
      - type
      type: object
      properties:
        description:
          type: string
          description: A description of the property that will be shown as help text in HubSpot.
        displayOrder:
          type: integer
          description: The order that this property should be displayed in the HubSpot UI relative to
            other properties for this object type. Properties are displayed in order starting with the
            lowest positive integer value. A value of -1 will cause the property to be displayed **after**
            any positive values.
          format: int32
        externalOptionsReferenceType:
          type: string
          description: Specifies the reference type for external options associated with the property.
        fieldType:
          type: string
          description: Controls how the property appears in HubSpot.
        formField:
          type: boolean
          description: Whether the property can be used in a HubSpot form.
        groupName:
          type: string
          description: The name of the group this property belongs to.
        hasUniqueValue:
          type: boolean
          description: Whether or not the property's value must be unique. Once set, this can't be changed.
        hidden:
          type: boolean
          description: Hidden options won't be shown in HubSpot.
        label:
          type: string
          description: A human-readable property label that will be shown in HubSpot.
        name:
          type: string
          description: The internal property name, which must be used when referencing the property from
            the API.
        numberDisplayHint:
          type: string
          description: Controls how numeric properties are formatted in the HubSpot UI
          enum:
          - currency
          - duration
          - formatted
          - percentage
          - probability
          - unformatted
        optionSortStrategy:
          type: string
          description: Controls how the property options will be sorted in the HubSpot UI.
          enum:
          - ALPHABETICAL
          - DISPLAY_ORDER
        options:
          type: array
          description: A list of available options for the property. This field is only required for enumerated
            properties.
          items:
            $ref: '#/components/schemas/OptionInput'
        referencedObjectType:
          type: string
          description: Defines the options this property will return, e.g. OWNER would return name of
            users on the portal.
        searchableInGlobalSearch:
          type: boolean
          description: Allow users to search for information entered to this field (limited to 3 properties)
        showCurrencySymbol:
          type: boolean
          description: Whether the property will display the currency symbol in the HubSpot UI.
        textDisplayHint:
          type: string
          description: Controls how text properties are formatted in the HubSpot UI
          enum:
          - domain_name
          - email
          - ip_address
          - multi_line
          - phone_number
          - physical_address
          - postal_code
          - unformatted_single_line
        type:
          type: string
          description: The data type of the property.
          enum:
          - bool
          - date
          - datetime
          - enumeration
          - number
          - phone_number
          - string
    Option:
      required:
      - hidden
      - label
      - value
      type: object
      properties:
        description:
          type: string
          description: A description of the option.
        displayOrder:
          type: integer
          description: Options are displayed in order starting with the lowest positive integer value.
            Values of -1 will cause the option to be displayed after any positive values.
          format: int32
        hidden:
          type: boolean
          description: Hidden options will not be displayed in HubSpot.
        label:
          type: string
          description: A human-readable option label that will be shown in HubSpot.
        value:
          type: string
          description: The internal value of the option, which must be used when setting the property
            value through the API.
      description: A HubSpot property option
    OptionInput:
      required:
      - displayOrder
      - hidden
      - label
      - value
      type: object
      properties:
        description:
          type: string
          description: A description of the option.
        displayOrder:
          type: integer
          description: Options are shown in order starting with the lowest positive integer value. Values
            of -1 will cause the option to be displayed after any positive values.
          format: int32
        hidden:
          type: boolean
          description: Hidden options won't be shown in HubSpot.
        label:
          type: string
          description: A human-readable option label that will be shown in HubSpot.
        value:
          type: string
          description: The internal value of the option, which must be used when setting the property
            value through the API.
    Property:
      required:
      - description
      - fieldType
      - groupName
      - label
      - name
      - options
      - type
      type: object
      properties:
        archived:
          type: boolean
          description: Whether or not the property is archived.
        archivedAt:
          type: string
          description: When the property was archived.
          format: date-time
        calculated:
          type: boolean
          description: For default properties, t

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