{
  "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" : "Get subscription definitions",
        "description" : "Get a list of all subscription definitions for the portal",
        "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" ]
        }, {
          "oauth2" : [ "communication_preferences.read" ]
        } ]
      }
    },
    "/communication-preferences/v3/status/email/{emailAddress}" : {
      "get" : {
        "tags" : [ "Basic" ],
        "summary" : "Get subscription statuses for a contact",
        "description" : "Returns a list of subscriptions and their status for a given contact.",
        "operationId" : "get-/communication-preferences/v3/status/email/{emailAddress}_getEmailStatus",
        "parameters" : [ {
          "name" : "emailAddress",
          "in" : "path",
          "description" : "The email address of the recipient whose subscription status you want to retrieve.",
          "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" ]
        }, {
          "oauth2" : [ "communication_preferences.read" ]
        } ]
      }
    },
    "/communication-preferences/v3/subscribe" : {
      "post" : {
        "tags" : [ "Advanced" ],
        "summary" : "Subscribe a contact",
        "description" : "Subscribes a contact to the given subscription type. This API is not valid to use for subscribing a contact at a brand or portal level and will return an error.",
        "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" ]
        }, {
          "oauth2" : [ "communication_preferences.write" ]
        } ]
      }
    },
    "/communication-preferences/v3/unsubscribe" : {
      "post" : {
        "tags" : [ "Advanced" ],
        "summary" : "Unsubscribe a contact",
        "description" : "Unsubscribes a contact from the given subscription type. This API is not valid to use for unsubscribing a contact at a brand or portal level and will return an error.",
        "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" ]
        }, {
          "oauth2" : [ "communication_preferences.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
          }
        },
        "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
          }
        },
        "example" : null
      },
      "PublicSubscriptionStatus" : {
        "required" : [ "description", "id", "name", "sourceOfStatus", "status" ],
        "type" : "object",
        "properties" : {
          "brandId" : {
            "type" : "integer",
            "description" : "The ID of the brand that the subscription is associated with, if there is one.",
            "format" : "int64",
            "example" : null
          },
          "description" : {
            "type" : "string",
            "description" : "A description of the subscription.",
            "example" : null
          },
          "id" : {
            "type" : "string",
            "description" : "The ID for the subscription.",
            "example" : null
          },
          "legalBasis" : {
            "type" : "string",
            "description" : "The legal reason for the current status of the subscription.",
            "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",
            "description" : "A more detailed explanation to go with the legal basis.",
            "example" : null
          },
          "name" : {
            "type" : "string",
            "description" : "The name of the subscription.",
            "example" : null
          },
          "preferenceGroupName" : {
            "type" : "string",
            "description" : "The name of the preferences group that the subscription is associated with.",
            "example" : null
          },
          "sourceOfStatus" : {
            "type" : "string",
            "description" : "Where the status is determined from e.g. PORTAL_WIDE_STATUS if the contact opted out from the portal.",
            "example" : null,
            "enum" : [ "BRAND_WIDE_STATUS", "PORTAL_WIDE_STATUS", "SUBSCRIPTION_STATUS" ]
          },
          "status" : {
            "type" : "string",
            "description" : "Whether the contact is subscribed.",
            "example" : null,
            "enum" : [ "NOT_SUBSCRIBED", "SUBSCRIBED" ]
          }
        },
        "example" : null
      },
      "PublicSubscriptionStatusesResponse" : {
        "required" : [ "recipient", "subscriptionStatuses" ],
        "type" : "object",
        "properties" : {
          "recipient" : {
            "type" : "string",
            "description" : "Email address of the contact.",
            "example" : null
          },
          "subscriptionStatuses" : {
            "type" : "array",
            "description" : "A list of all of the contact's subscriptions statuses.",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/PublicSubscriptionStatus"
            }
          }
        },
        "example" : null
      },
      "PublicSubscriptionTranslation" : {
        "required" : [ "createdAt", "description", "languageCode", "name", "subscriptionId", "updatedAt" ],
        "type" : "object",
        "properties" : {
          "createdAt" : {
            "type" : "integer",
            "description" : "A Unix timestamp in milliseconds indicating when the translation was created. It is an integer.",
            "format" : "int64",
            "example" : null
          },
          "description" : {
            "type" : "string",
            "description" : "A string providing a description of the subscription in the specified language.",
            "example" : null
          },
          "languageCode" : {
            "type" : "string",
            "description" : "The code representing the language of the translation. It is a string.",
            "example" : null
          },
          "name" : {
            "type" : "string",
            "description" : "The localized name of the subscription. It is a string.",
            "example" : null
          },
          "subscriptionId" : {
            "type" : "integer",
            "description" : "The unique identifier for the subscription, represented as an integer.",
            "format" : "int64",
            "example" : null
          },
          "updatedAt" : {
            "type" : "integer",
            "description" : "A timestamp indicating when the translation was last updated, represented as an integer.",
            "format" : "int64",
            "example" : null
          }
        },
        "example" : null
      },
      "PublicUpdateSubscriptionStatusRequest" : {
        "required" : [ "emailAddress", "subscriptionId" ],
        "type" : "object",
        "properties" : {
          "emailAddress" : {
            "type" : "string",
            "description" : "Contact's email address.",
            "example" : null
          },
          "legalBasis" : {
            "type" : "string",
            "description" : "Legal basis for updating the contact's status (required for GDPR enabled portals).",
            "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",
            "description" : "A more detailed explanation to go with the legal basis (required for GDPR enabled portals).",
            "example" : null
          },
          "subscriptionId" : {
            "type" : "string",
            "description" : "ID of the subscription being updated for the contact.",
            "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 definition.",
            "format" : "int64",
            "example" : null
          },
          "communicationMethod" : {
            "type" : "string",
            "description" : "The method or technology used to contact.",
            "example" : null
          },
          "createdAt" : {
            "type" : "string",
            "description" : "Time at which the definition was created.",
            "format" : "date-time",
            "example" : null
          },
          "description" : {
            "type" : "string",
            "description" : "A description of the subscription.",
            "example" : null
          },
          "id" : {
            "type" : "string",
            "description" : "The ID of the definition.",
            "example" : null
          },
          "isActive" : {
            "type" : "boolean",
            "description" : "Whether the definition is active or archived.",
            "example" : null
          },
          "isDefault" : {
            "type" : "boolean",
            "description" : "A subscription definition created by HubSpot.",
            "example" : null
          },
          "isInternal" : {
            "type" : "boolean",
            "description" : "A default description that is used by some HubSpot tools and cannot be edited.",
            "example" : null
          },
          "name" : {
            "type" : "string",
            "description" : "The name of the subscription.",
            "example" : null
          },
          "purpose" : {
            "type" : "string",
            "description" : "The purpose of this subscription or the department in your organization that uses it.",
            "example" : null
          },
          "subscriptionTranslations" : {
            "type" : "array",
            "description" : "An array of translations for the subscription, each represented by a PublicSubscriptionTranslation object.",
            "example" : null,
            "items" : {
              "$ref" : "#/components/schemas/PublicSubscriptionTranslation"
            }
          },
          "updatedAt" : {
            "type" : "string",
            "description" : "Time at which the definition was last updated.",
            "format" : "date-time",
            "example" : null
          }
        },
        "example" : null
      },
      "SubscriptionDefinitionsResponse" : {
        "required" : [ "subscriptionDefinitions" ],
        "type" : "object",
        "properties" : {
          "subscriptionDefinitions" : {
            "type" : "array",
            "description" : "A list of all subscription definitions.",
            "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" : "",
              "subscriptions-status-resubscribe-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"
  }
}