{
  "openapi" : "3.0.1",
  "info" : {
    "title" : "Communication Preferences Subscriptions",
    "description" : "Basepom for all HubSpot Projects",
    "version" : "v3",
    "x-hubspot-product-tier-requirements" : {
      "marketing" : "ENTERPRISE",
      "sales" : "FREE",
      "service" : "FREE",
      "cms" : "FREE",
      "commerce" : "FREE",
      "crmHub" : "FREE",
      "dataHub" : "FREE"
    },
    "x-hubspot-related-documentation" : [ {
      "name" : "Subscription Preferences Guide",
      "url" : "https://developers.hubspot.com/docs/guides/api/marketing/subscriptions-preferences"
    } ]
  },
  "servers" : [ {
    "url" : "https://api.hubapi.com"
  } ],
  "tags" : [ {
    "name" : "Advanced"
  }, {
    "name" : "Basic"
  } ],
  "paths" : {
    "/communication-preferences/v3/definitions" : {
      "get" : {
        "tags" : [ "Basic" ],
        "summary" : "Retrieve all subscription status definitions",
        "description" : "Get a list of subscription status definitions from the account.",
        "operationId" : "get-/communication-preferences/v3/definitions_getPage",
        "parameters" : [ ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/SubscriptionDefinitionsResponse"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "communication_preferences.read_write" ]
        } ]
      }
    },
    "/communication-preferences/v3/status/email/{emailAddress}" : {
      "get" : {
        "tags" : [ "Basic" ],
        "operationId" : "get-/communication-preferences/v3/status/email/{emailAddress}_getEmailStatus",
        "parameters" : [ {
          "name" : "emailAddress",
          "in" : "path",
          "required" : true,
          "style" : "simple",
          "explode" : false,
          "schema" : {
            "type" : "string",
            "example" : null
          }
        } ],
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/PublicSubscriptionStatusesResponse"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "communication_preferences.read_write" ]
        } ]
      }
    },
    "/communication-preferences/v3/subscribe" : {
      "post" : {
        "tags" : [ "Advanced" ],
        "operationId" : "post-/communication-preferences/v3/subscribe_subscribe",
        "parameters" : [ ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/PublicUpdateSubscriptionStatusRequest"
              },
              "example" : null
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/PublicSubscriptionStatus"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "communication_preferences.read_write" ]
        } ]
      }
    },
    "/communication-preferences/v3/unsubscribe" : {
      "post" : {
        "tags" : [ "Advanced" ],
        "operationId" : "post-/communication-preferences/v3/unsubscribe_unsubscribe",
        "parameters" : [ ],
        "requestBody" : {
          "content" : {
            "application/json" : {
              "schema" : {
                "$ref" : "#/components/schemas/PublicUpdateSubscriptionStatusRequest"
              },
              "example" : null
            }
          },
          "required" : true
        },
        "responses" : {
          "200" : {
            "description" : "successful operation",
            "content" : {
              "application/json" : {
                "schema" : {
                  "$ref" : "#/components/schemas/PublicSubscriptionStatus"
                },
                "example" : null
              }
            }
          },
          "default" : {
            "description" : "",
            "$ref" : "#/components/responses/Error"
          }
        },
        "security" : [ {
          "oauth2" : [ "communication_preferences.read_write" ]
        } ]
      }
    }
  },
  "components" : {
    "schemas" : {
      "Error" : {
        "required" : [ "category", "correlationId", "message" ],
        "type" : "object",
        "properties" : {
          "category" : {
            "type" : "string",
            "description" : "The error category",
            "example" : null
          },
          "context" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "array",
              "example" : null,
              "items" : {
                "type" : "string",
                "example" : null
              }
            },
            "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",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/ErrorDetail"
            }
          },
          "links" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "string",
              "example" : null
            },
            "description" : "A map of link names to associated URIs containing documentation about the error or recommended remediation steps",
            "example" : null
          },
          "message" : {
            "type" : "string",
            "description" : "A human readable message describing the error along with remediation steps where appropriate",
            "example" : "An error occurred"
          },
          "subCategory" : {
            "type" : "string",
            "description" : "A specific category that contains more specific detail about the error",
            "example" : null
          }
        },
        "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",
            "example" : null
          },
          "context" : {
            "type" : "object",
            "additionalProperties" : {
              "type" : "array",
              "example" : null,
              "items" : {
                "type" : "string",
                "example" : null
              }
            },
            "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.",
            "example" : null
          },
          "message" : {
            "type" : "string",
            "description" : "A human readable message describing the error along with remediation steps where appropriate",
            "example" : null
          },
          "subCategory" : {
            "type" : "string",
            "description" : "A specific category that contains more specific detail about the error",
            "example" : null
          }
        },
        "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.",
        "example" : null
      },
      "PublicSubscriptionStatus" : {
        "required" : [ "description", "id", "name", "sourceOfStatus", "status" ],
        "type" : "object",
        "properties" : {
          "brandId" : {
            "type" : "integer",
            "format" : "int64",
            "example" : null
          },
          "description" : {
            "type" : "string",
            "example" : null
          },
          "id" : {
            "type" : "string",
            "example" : null
          },
          "legalBasis" : {
            "type" : "string",
            "example" : null,
            "enum" : [ "CONSENT_WITH_NOTICE", "LEGITIMATE_INTEREST_CLIENT", "LEGITIMATE_INTEREST_OTHER", "LEGITIMATE_INTEREST_PQL", "NON_GDPR", "PERFORMANCE_OF_CONTRACT", "PROCESS_AND_STORE" ]
          },
          "legalBasisExplanation" : {
            "type" : "string",
            "example" : null
          },
          "name" : {
            "type" : "string",
            "example" : null
          },
          "preferenceGroupName" : {
            "type" : "string",
            "example" : null
          },
          "sourceOfStatus" : {
            "type" : "string",
            "example" : null,
            "enum" : [ "BRAND_WIDE_STATUS", "PORTAL_WIDE_STATUS", "SUBSCRIPTION_STATUS" ]
          },
          "status" : {
            "type" : "string",
            "example" : null,
            "enum" : [ "NOT_SUBSCRIBED", "SUBSCRIBED" ]
          }
        },
        "example" : null
      },
      "PublicSubscriptionStatusesResponse" : {
        "required" : [ "recipient", "subscriptionStatuses" ],
        "type" : "object",
        "properties" : {
          "recipient" : {
            "type" : "string",
            "example" : null
          },
          "subscriptionStatuses" : {
            "type" : "array",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/PublicSubscriptionStatus"
            }
          }
        },
        "example" : null
      },
      "PublicSubscriptionTranslation" : {
        "required" : [ "createdAt", "description", "languageCode", "name", "subscriptionId", "updatedAt" ],
        "type" : "object",
        "properties" : {
          "createdAt" : {
            "type" : "integer",
            "description" : "The timestamp indicating when the subscription translation was created.",
            "format" : "int64",
            "example" : null
          },
          "description" : {
            "type" : "string",
            "description" : "A text description of the subscription translation.",
            "example" : null
          },
          "languageCode" : {
            "type" : "string",
            "description" : "The code representing the language of the subscription translation.",
            "example" : null
          },
          "name" : {
            "type" : "string",
            "description" : "The name of the subscription translation.",
            "example" : null
          },
          "subscriptionId" : {
            "type" : "integer",
            "description" : "The unique identifier for the subscription associated with the translation.",
            "format" : "int64",
            "example" : null
          },
          "updatedAt" : {
            "type" : "integer",
            "description" : "The timestamp indicating when the subscription translation was last updated.",
            "format" : "int64",
            "example" : null
          }
        },
        "example" : null
      },
      "PublicUpdateSubscriptionStatusRequest" : {
        "required" : [ "emailAddress", "subscriptionId" ],
        "type" : "object",
        "properties" : {
          "emailAddress" : {
            "type" : "string",
            "example" : null
          },
          "legalBasis" : {
            "type" : "string",
            "example" : null,
            "enum" : [ "CONSENT_WITH_NOTICE", "LEGITIMATE_INTEREST_CLIENT", "LEGITIMATE_INTEREST_OTHER", "LEGITIMATE_INTEREST_PQL", "NON_GDPR", "PERFORMANCE_OF_CONTRACT", "PROCESS_AND_STORE" ]
          },
          "legalBasisExplanation" : {
            "type" : "string",
            "example" : null
          },
          "subscriptionId" : {
            "type" : "string",
            "example" : null
          }
        },
        "example" : null
      },
      "SubscriptionDefinition" : {
        "required" : [ "createdAt", "description", "id", "isActive", "isDefault", "isInternal", "name", "updatedAt" ],
        "type" : "object",
        "properties" : {
          "businessUnitId" : {
            "type" : "integer",
            "description" : "The ID of the business unit associated with the subscription.",
            "format" : "int64",
            "example" : null
          },
          "communicationMethod" : {
            "type" : "string",
            "description" : "The method of communication for the subscription.",
            "example" : null
          },
          "createdAt" : {
            "type" : "string",
            "description" : "The date and time when the subscription was created.",
            "format" : "date-time",
            "example" : null
          },
          "description" : {
            "type" : "string",
            "description" : "A description of the subscription.",
            "example" : null
          },
          "id" : {
            "type" : "string",
            "description" : "The unique identifier for the subscription.",
            "example" : null
          },
          "isActive" : {
            "type" : "boolean",
            "description" : "Indicates whether the subscription is active.",
            "example" : null
          },
          "isDefault" : {
            "type" : "boolean",
            "description" : "Indicates whether the subscription is the default option.",
            "example" : null
          },
          "isInternal" : {
            "type" : "boolean",
            "description" : "Indicates whether the subscription is internal.",
            "example" : null
          },
          "name" : {
            "type" : "string",
            "description" : "The name of the subscription.",
            "example" : null
          },
          "purpose" : {
            "type" : "string",
            "description" : "The purpose of the subscription.",
            "example" : null
          },
          "subscriptionTranslations" : {
            "type" : "array",
            "description" : "A list of translations associated with the subscription.",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/PublicSubscriptionTranslation"
            }
          },
          "updatedAt" : {
            "type" : "string",
            "description" : "The date and time when the subscription was last updated.",
            "format" : "date-time",
            "example" : null
          }
        },
        "example" : null
      },
      "SubscriptionDefinitionsResponse" : {
        "required" : [ "subscriptionDefinitions" ],
        "type" : "object",
        "properties" : {
          "subscriptionDefinitions" : {
            "type" : "array",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/SubscriptionDefinition"
            }
          }
        },
        "example" : null
      }
    },
    "responses" : {
      "Error" : {
        "description" : "An error occurred.",
        "content" : {
          "*/*" : {
            "schema" : {
              "$ref" : "#/components/schemas/Error"
            },
            "example" : null
          }
        }
      }
    },
    "securitySchemes" : {
      "developer_hapikey" : {
        "type" : "apiKey",
        "name" : "hapikey",
        "in" : "query"
      },
      "oauth2" : {
        "type" : "oauth2",
        "flows" : {
          "authorizationCode" : {
            "authorizationUrl" : "https://app.hubspot.com/oauth/authorize",
            "tokenUrl" : "https://api.hubapi.com/oauth/v1/token",
            "scopes" : {
              "communication_preferences.read_write" : ""
            }
          }
        }
      },
      "private_apps" : {
        "type" : "apiKey",
        "name" : "private-app",
        "in" : "header"
      },
      "private_apps_legacy" : {
        "type" : "apiKey",
        "name" : "private-app-legacy",
        "in" : "header"
      }
    }
  },
  "x-hubspot-available-client-libraries" : [ "Node", "Python", "Ruby", "PHP" ],
  "x-hubspot-product-tier-requirements" : {
    "marketing" : "ENTERPRISE",
    "sales" : "FREE",
    "service" : "FREE",
    "cms" : "FREE",
    "commerce" : "FREE",
    "crmHub" : "FREE",
    "dataHub" : "FREE"
  }
}