openapi-directory/api/hubapi.com/crm.json

Building & bundling https://github.com/APIs-guru/openapi-directory for easy use from JS

{"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":"2025-04-15T13:51:49.825Z"}]}],"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":"2025-04-15T13:51:49.825Z","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":"2025-04-15T13:51:49.825Z"}]},"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":"2025-04-15T13:51:49.825Z","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":"2025-04-15T13:51:49.825Z"},"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":"2025-04-15T13:51:49.825Z","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":"2025-04-15T13:51:49.825Z"},"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":"2025-04-15T13:51:49.825Z","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":"2025-04-15T13:51:49.825Z"},"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"}}}}