openapi: 3.0.1
servers:
  - url: https://api.hubapi.com/crm/v3/extensions/cards
info:
  description: Allows an app to extend the CRM UI by surfacing custom cards in the sidebar of record pages. These cards are defined up-front as part of app configuration, then populated by external data fetch requests when the record page is accessed by a user.
  title: CRM cards
  version: v3
  x-logo:
    url: https://developers.hubspot.com/hubfs/assets/hubspot.com/buzz/HubSpotOpenGraph.png
  x-origin:
    - format: openapi
      url: https://api.hubspot.com/api-catalog-public/v1/apis/extensions/sales-objects/v1/object-types
      version: "3.0"
  x-providerName: hubapi.com
  x-serviceName: crm
tags:
  - description: Definitions and configuration for the CRM cards your app can display.
    name: Cards
  - description: Operations related to card detail responses sent to HubSpot by an app.
    name: SampleResponse
paths:
  /sample-response:
    get:
      description: Returns an example card detail response. This is the payload with displayed details for a card that will be shown to a user. An app should send this in response to the data fetch request.
      operationId: get-/crm/v3/extensions/cards/sample-response
      responses:
        "200":
          content:
            application/json:
              example:
                allItemsLinkUrl: https://example.com/all-items-link-url
                cardLabel: Tickets
                responseVersion: v3
                sections:
                  - actions:
                      - httpMethod: POST
                        label: action-hook-label
                        propertyNamesIncluded:
                          - email
                          - firstName
                        type: ACTION_HOOK
                        url: https://example.com/action-hook-frame
                      - confirmation:
                          cancelButtonLabel: Cancel
                          confirmButtonLabel: Continue
                          prompt: action-confirmation-body-prompt
                        httpMethod: POST
                        label: confirmation-hook-label
                        propertyNamesIncluded: []
                        type: ACTION_HOOK
                        url: https://example.com/confirmation-action-hook
                      - height: 480
                        label: iframe-action-label
                        propertyNamesIncluded:
                          - property1
                          - property2
                          - property3
                        type: IFRAME
                        url: https://example.com/iframe-action-label
                        width: 640
                    id: "123"
                    linkUrl: http://example.com/1
                    title: "API-22: APIs working too fast"
                    tokens:
                      - dataType: DATE
                        label: test_label
                        name: created
                        value: 2016-08-04
                topLevelActions:
                  primary:
                    height: 480
                    label: test_label_primary
                    propertyNamesIncluded: []
                    type: IFRAME
                    url: https://example.com/primary-iframe
                    width: 640
                  secondary:
                    - height: 480
                      label: test_label_secondary
                      propertyNamesIncluded: []
                      type: IFRAME
                      url: https://example.com/secondary-iframe
                      width: 640
                  settings:
                    height: 480
                    label: Edit
                    propertyNamesIncluded:
                      - some_crm_property
                    type: IFRAME
                    url: https://example.com/iframe-contents
                    width: 640
                totalCount: 1
              schema:
                $ref: "#/components/schemas/IntegratorCardPayloadResponse"
          description: successful operation
        default:
          $ref: "#/components/responses/Error"
      security: []
      summary: Get sample card detail response
      tags:
        - SampleResponse
  /{appId}:
    get:
      description: Returns a list of cards for a given app.
      operationId: get-/crm/v3/extensions/cards/{appId}
      parameters:
        - description: The ID of the target app.
          explode: false
          in: path
          name: appId
          required: true
          schema:
            format: int32
            type: integer
          style: simple
      responses:
        "200":
          content:
            application/json:
              example:
                results:
                  - actions:
                      baseUrls:
                        - https://www.example.com/hubspot
                    createdAt: 2020-02-26T18:30:53.451Z
                    display:
                      properties:
                        - dataType: STRING
                          label: Pets Name
                          name: pet_name
                    fetch:
                      objectTypes:
                        - name: contacts
                          propertiesToSend:
                            - email
                            - firstname
                      targetUrl: https://www.example.com/hubspot/target
                    id: "123"
                    title: PetSpot
                    updatedAt: 2020-02-26T18:30:53.451Z
              schema:
                $ref: "#/components/schemas/CardListResponse"
          description: successful operation
        default:
          $ref: "#/components/responses/Error"
      security:
        - developer_hapikey: []
      summary: Get all cards
      tags:
        - Cards
    post:
      description: Defines a new card that will become active on an account when this app is installed.
      operationId: post-/crm/v3/extensions/cards/{appId}
      parameters:
        - description: The ID of the target app.
          explode: false
          in: path
          name: appId
          required: true
          schema:
            format: int32
            type: integer
          style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CardCreateRequest"
        description: The new card definition.
        required: true
      responses:
        "201":
          content:
            application/json:
              example:
                actions:
                  baseUrls:
                    - https://www.example.com/hubspot
                createdAt: 2019-10-30T03:30:17.883Z
                display:
                  properties:
                    - dataType: STRING
                      label: Pet's Name
                      name: pet_name
                fetch:
                  objectTypes:
                    - name: contacts
                      propertiesToSend:
                        - email
                        - firstname
                  targetUrl: https://www.example.com/hubspot/target
                title: PetSpot
                updatedAt: 2019-11-30T03:30:17.883Z
              schema:
                $ref: "#/components/schemas/CardResponse"
          description: successful operation
        default:
          $ref: "#/components/responses/Error"
      security:
        - developer_hapikey: []
      summary: Create a new card
      tags:
        - Cards
  /{appId}/{cardId}:
    delete:
      description: Permanently deletes a card definition with the given ID. Once deleted, data fetch requests for this card will no longer be sent to your service. This can't be undone.
      operationId: delete-/crm/v3/extensions/cards/{appId}/{cardId}
      parameters:
        - description: The ID of the target app.
          explode: false
          in: path
          name: appId
          required: true
          schema:
            format: int32
            type: integer
          style: simple
        - description: The ID of the card to delete.
          explode: false
          in: path
          name: cardId
          required: true
          schema:
            type: string
          style: simple
      responses:
        "204":
          content: {}
          description: No content
        default:
          $ref: "#/components/responses/Error"
      security:
        - developer_hapikey: []
      summary: Delete a card
      tags:
        - Cards
    get:
      description: Returns the definition for a card with the given ID.
      operationId: get-/crm/v3/extensions/cards/{appId}/{cardId}
      parameters:
        - description: The ID of the target app.
          explode: false
          in: path
          name: appId
          required: true
          schema:
            format: int32
            type: integer
          style: simple
        - description: The ID of the target card.
          explode: false
          in: path
          name: cardId
          required: true
          schema:
            type: string
          style: simple
      responses:
        "200":
          content:
            application/json:
              example:
                actions:
                  baseUrls:
                    - https://www.example.com/hubspot
                createdAt: 2019-10-30T03:30:17.883Z
                display:
                  properties:
                    - dataType: STRING
                      label: Pets Name
                      name: pet_name
                fetch:
                  objectTypes:
                    - name: contacts
                      propertiesToSend:
                        - email
                        - firstname
                  targetUrl: https://www.example.com/hubspot/target
                title: PetSpot
                updatedAt: 2019-11-30T03:30:17.883Z
              schema:
                $ref: "#/components/schemas/CardResponse"
          description: successful operation
        default:
          $ref: "#/components/responses/Error"
      security:
        - developer_hapikey: []
      summary: Get a card.
      tags:
        - Cards
    patch:
      description: Update a card definition with new details.
      operationId: patch-/crm/v3/extensions/cards/{appId}/{cardId}
      parameters:
        - description: The ID of the target app.
          explode: false
          in: path
          name: appId
          required: true
          schema:
            format: int32
            type: integer
          style: simple
        - description: The ID of the card to update.
          explode: false
          in: path
          name: cardId
          required: true
          schema:
            type: string
          style: simple
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CardPatchRequest"
        description: Card definition fields to be updated.
        required: true
      responses:
        "200":
          content:
            application/json:
              example:
                actions:
                  baseUrls:
                    - https://www.example.com/hubspot
                createdAt: 2019-10-30T03:30:17.883Z
                display:
                  properties:
                    - dataType: STRING
                      label: Pets Name
                      name: pet_name
                fetch:
                  objectTypes:
                    - name: contacts
                      propertiesToSend:
                        - email
                        - firstname
                  targetUrl: https://www.example.com/hubspot/target
                title: PetSpot
                updatedAt: 2019-11-30T03:30:17.883Z
              schema:
                $ref: "#/components/schemas/CardResponse"
          description: successful operation
        default:
          $ref: "#/components/responses/Error"
      security:
        - developer_hapikey: []
      summary: Update a card
      tags:
        - Cards
components:
  responses:
    Error:
      content:
        "*/*":
          schema:
            $ref: "#/components/schemas/Error"
      description: An error occurred.
  schemas:
    ActionConfirmationBody:
      properties:
        cancelButtonLabel:
          type: string
        confirmButtonLabel:
          type: string
        prompt:
          type: string
      required:
        - cancelButtonLabel
        - confirmButtonLabel
        - prompt
      type: object
    ActionHookActionBody:
      properties:
        confirmation:
          $ref: "#/components/schemas/ActionConfirmationBody"
        httpMethod:
          enum:
            - CONNECT
            - DELETE
            - GET
            - HEAD
            - OPTIONS
            - PATCH
            - POST
            - PUT
            - TRACE
          type: string
        label:
          type: string
        propertyNamesIncluded:
          items:
            type: string
          type: array
        type:
          default: ACTION_HOOK
          enum:
            - ACTION_HOOK
          type: string
        url:
          type: string
      required:
        - httpMethod
        - propertyNamesIncluded
        - type
        - url
      title: ACTION_HOOK
      type: object
    CardActions:
      description: Configuration for custom user actions on cards.
      example:
        baseUrls:
          - https://www.example.com/hubspot
      properties:
        baseUrls:
          description: A list of URL prefixes that will be accepted for card action URLs. If your data fetch response includes an action URL that doesn't begin with one of these values, it will result in an error and the card will not be displayed.
          items:
            type: string
          type: array
      required:
        - baseUrls
      type: object
    CardCreateRequest:
      description: State of card definition to be created
      example:
        actions:
          baseUrls:
            - https://www.example.com/hubspot
        display:
          properties:
            dataType: STRING
            label: Pets Name
            name: pet_name
        fetch:
          objectTypes:
            - name: contacts
              propertiesToSend:
                - email
                - firstname
          targetUrl: https://www.example.com/hubspot/target
        title: PetSpot
      properties:
        actions:
          $ref: "#/components/schemas/CardActions"
        display:
          $ref: "#/components/schemas/CardDisplayBody"
        fetch:
          $ref: "#/components/schemas/CardFetchBody"
        title:
          description: The top-level title for this card. Displayed to users in the CRM UI.
          type: string
      required:
        - actions
        - display
        - fetch
        - title
      type: object
    CardDisplayBody:
      description: Configuration for displayed info on a card
      properties:
        properties:
          description: 'Card display properties. These will will be rendered as "label : value" pairs in the card UI. See the [example card](#) in the overview docs for more details.'
          items:
            $ref: "#/components/schemas/CardDisplayProperty"
          type: array
      required:
        - properties
      type: object
    CardDisplayProperty:
      description: Definition for a card display property.
      properties:
        dataType:
          description: Type of data represented by this property.
          enum:
            - BOOLEAN
            - CURRENCY
            - DATE
            - DATETIME
            - EMAIL
            - LINK
            - NUMERIC
            - STRING
            - STATUS
          type: string
        label:
          description: The label for this property as you'd like it displayed to users.
          type: string
        name:
          description: An internal identifier for this property. This value must be unique TODO.
          type: string
        options:
          description: An array of available options that can be displayed. Only used in when `dataType` is `STATUS`.
          items:
            $ref: "#/components/schemas/DisplayOption"
          type: array
      required:
        - dataType
        - label
        - name
        - options
      type: object
    CardFetchBody:
      description: Configuration for this card's data fetch request.
      properties:
        objectTypes:
          description: An array of CRM object types where this card should be displayed. HubSpot will call your data fetch URL whenever a user visits a record page of the types defined here.
          items:
            $ref: "#/components/schemas/CardObjectTypeBody"
          type: array
        targetUrl:
          description: URL to a service endpoints that will respond with card details. HubSpot will call this endpoint each time a user visits a CRM record page where this card should be displayed.
          type: string
      required:
        - objectTypes
        - targetUrl
      type: object
    CardFetchBodyPatch:
      description: Variant of CardFetchBody with fields as optional for patches
      properties:
        objectTypes:
          description: An array of CRM object types where this card should be displayed. HubSpot will call your target URL whenever a user visits a record page of the types defined here.
          items:
            $ref: "#/components/schemas/CardObjectTypeBody"
          type: array
        targetUrl:
          description: URL to a service endpoint that will respond with details for this card. HubSpot will call this endpoint each time a user visits a CRM record page where this card should be displayed.
          type: string
      required:
        - objectTypes
      type: object
    CardListResponse:
      description: List of card definitions
      properties:
        results:
          description: List of card definitions
          items:
            $ref: "#/components/schemas/CardResponse"
          type: array
      required:
        - results
      type: object
    CardObjectTypeBody:
      properties:
        name:
          description: A CRM object type where this card should be displayed.
          enum:
            - contacts
            - deals
            - companies
            - tickets
          type: string
        propertiesToSend:
          description: An array of properties that should be sent to this card's target URL when the data fetch request is made. Must be valid properties for the corresponding CRM object type.
          items:
            type: string
          type: array
      required:
        - name
        - propertiesToSend
      type: object
    CardPatchRequest:
      description: Body for a patch with optional fields
      example:
        actions:
          baseUrls:
            - https://www.example.com/hubspot
        display:
          properties:
            dataType: STRING
            label: Pets Name
            name: pet_name
        fetch:
          objectTypes:
            - name: contacts
              propertiesToSend:
                - email
                - firstname
          targetUrl: https://www.example.com/hubspot/target
        title: PetSpot
      properties:
        actions:
          $ref: "#/components/schemas/CardActions"
        display:
          $ref: "#/components/schemas/CardDisplayBody"
        fetch:
          $ref: "#/components/schemas/CardFetchBodyPatch"
        title:
          description: The top-level title for this card. Displayed to users in the CRM UI.
          type: string
      type: object
    CardResponse:
      description: Current state of Card Definition
      properties:
        actions:
          $ref: "#/components/schemas/CardActions"
        createdAt:
          description: When this card was created.
          format: date-time
          type: string
        display:
          $ref: "#/components/schemas/CardDisplayBody"
        fetch:
          $ref: "#/components/schemas/CardFetchBody"
        id:
          description: Generated unique ID for card.
          type: string
        title:
          description: Displayed title of this card.
          type: string
        updatedAt:
          description: The last time this card was updated.
          format: date-time
          type: string
      required:
        - actions
        - display
        - fetch
        - id
        - title
      type: object
    DisplayOption:
      description: Option definition for STATUS dataTypes.
      properties:
        label:
          description: The text that will be displayed to users for this option.
          type: string
        name:
          description: JSON-friendly unique name for option.
          type: string
        type:
          description: The type of status.
          enum:
            - DEFAULT
            - SUCCESS
            - WARNING
            - DANGER
            - INFO
          type: string
      required:
        - label
        - name
        - type
      type: object
    Error:
      example:
        category: VALIDATION_ERROR
        correlationId: aeb5f871-7f07-4993-9211-075dc63e7cbf
        links:
          knowledge-base: https://www.hubspot.com/products/service/knowledge-base
        message: Invalid input (details will vary based on the error)
      properties:
        category:
          description: The error category
          type: string
        context:
          additionalProperties:
            items:
              type: string
            type: array
          description: Context about the error condition
          example:
            invalidPropertyName:
              - propertyValue
            missingScopes:
              - scope1
              - scope2
          type: object
        correlationId:
          description: A unique identifier for the request. Include this value with any error reports or support tickets
          example: aeb5f871-7f07-4993-9211-075dc63e7cbf
          format: uuid
          type: string
        errors:
          description: further information about the error
          items:
            $ref: "#/components/schemas/ErrorDetail"
          type: array
        links:
          additionalProperties:
            type: string
          description: A map of link names to associated URIs containing documentation about the error or recommended remediation steps
          type: object
        message:
          description: A human readable message describing the error along with remediation steps where appropriate
          example: An error occurred
          type: string
        subCategory:
          description: A specific category that contains more specific detail about the error
          type: string
      required:
        - category
        - correlationId
        - message
      type: object
    ErrorDetail:
      properties:
        code:
          description: The status code associated with the error detail
          type: string
        context:
          additionalProperties:
            items:
              type: string
            type: array
          description: Context about the error condition
          example:
            missingScopes:
              - scope1
              - scope2
          type: object
        in:
          description: The name of the field or parameter in which the error was found.
          type: string
        message:
          description: A human readable message describing the error along with remediation steps where appropriate
          type: string
        subCategory:
          description: A specific category that contains more specific detail about the error
          type: string
      required:
        - message
      type: object
    IFrameActionBody:
      properties:
        height:
          format: int32
          type: integer
        label:
          type: string
        propertyNamesIncluded:
          items:
            type: string
          type: array
        type:
          default: IFRAME
          enum:
            - IFRAME
          type: string
        url:
          type: string
        width:
          format: int32
          type: integer
      required:
        - height
        - propertyNamesIncluded
        - type
        - url
        - width
      title: IFRAME
      type: object
    IntegratorCardPayloadResponse:
      description: The card details payload, sent to HubSpot by an app in response to a data fetch request when a user visits a CRM record page.
      properties:
        allItemsLinkUrl:
          description: URL to a page the integrator has built that displays all details for this card. This URL will be displayed to users under a `See more [x]` link if there are more than five items in your response, where `[x]` is the value of `itemLabel`.
          type: string
        cardLabel:
          description: The label to be used for the `allItemsLinkUrl` link (e.g. 'See more tickets'). If not provided, this falls back to the card's title.
          type: string
        responseVersion:
          enum:
            - v1
            - v3
          type: string
        sections:
          description: A list of up to five valid card sub categories.
          items:
            $ref: "#/components/schemas/IntegratorObjectResult"
          type: array
        topLevelActions:
          $ref: "#/components/schemas/TopLevelActions"
        totalCount:
          description: The total number of card properties that will be sent in this response.
          format: int32
          type: integer
      required:
        - totalCount
      type: object
    IntegratorObjectResult:
      properties:
        actions:
          items:
            oneOf:
              - $ref: "#/components/schemas/ActionHookActionBody"
              - $ref: "#/components/schemas/IFrameActionBody"
          type: array
        id:
          type: string
        linkUrl:
          type: string
        title:
          type: string
        tokens:
          items:
            $ref: "#/components/schemas/ObjectToken"
          type: array
      required:
        - actions
        - id
        - title
        - tokens
      type: object
    ObjectToken:
      properties:
        dataType:
          enum:
            - BOOLEAN
            - CURRENCY
            - DATE
            - DATETIME
            - EMAIL
            - LINK
            - NUMERIC
            - STRING
            - STATUS
          type: string
        label:
          type: string
        name:
          type: string
        value:
          type: string
      required:
        - value
      type: object
    TopLevelActions:
      properties:
        primary:
          oneOf:
            - $ref: "#/components/schemas/ActionHookActionBody"
            - $ref: "#/components/schemas/IFrameActionBody"
        secondary:
          items:
            oneOf:
              - $ref: "#/components/schemas/ActionHookActionBody"
              - $ref: "#/components/schemas/IFrameActionBody"
          type: array
        settings:
          $ref: "#/components/schemas/IFrameActionBody"
      required:
        - secondary
      type: object
  securitySchemes:
    developer_hapikey:
      in: query
      name: hapikey
      type: apiKey