openapi: 3.0.0
servers:
  - url: https://api.enzoic.com/v1
info:
  description: This is the public developer API for Enzoic
  version: "1.0.0"
  title: Enzoic API
  contact:
    email: support@enzoic.com
  license:
    name: Commercial
    url: 'https://www.enzoic.com/terms-of-service'
tags:
  - name: account
    description: APIs which query account status and usage
  - name: breachMonitoring
    description: APIs which are used to set targets for breach monitoring
  - name: credentials
    description: APIs related to checking compromise status of a username/password combo
  - name: exposures
    description: APIs related to lookup information about exposures
  - name: passwords
    description: APIs related to checking compromise status of a password
paths:
  /account-status:
    get:
      security:
        - enzoic_auth: []
      tags:
        - account
      summary: query current usage of your account
      operationId: accountStatus
      description: |
        The Account Status API allows you to query the current usage of your Enzoic account.  Returns basic API usage stats for your account for the current billing period. Note that current usage numbers may be up to 5 minutes behind.
      responses:
        '200':
          description: The response contains current usage statistics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountStatusResponse'
  /account-usage:
    get:
      security:
        - enzoic_auth: []
      tags:
        - account
      summary: query detailed usage of your account
      operationId: accountUsage
      description: |
        Returns extended API usage stats for your account for the specified month and year, including efficacy reporting. Note that current usage numbers may be up to 5 minutes behind.
      parameters:
        - name: month
          in: query
          required: false
          description: The numeric month you wish to retrieve data for (1-12).  Defaults to the current month.
          example: 10
          schema:
            type: integer
        - name: year
          in: query
          required: false
          description: The full year you wish to retrieve data for (e.g. 2023)
          example: 2023
          schema:
            type: integer
      responses:
        '200':
          description: The response contains requested usage statistics.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountUsageResponse'
  /breach-monitoring-for-users:
    post:
      security:
        - enzoic_auth: []
      tags:
        - breachMonitoring
      summary: Create Exposure alert subscriptions for one or more usernames.
      operationId: addBreachMonitoringForUsers
      description: Allows you to setup a new exposure alert subscription for one or more email addresses. For additional privacy and security, emails are submitted as SHA256 hashes.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserBreachMonitoringPostBody'
      responses:
        '201':
          description: The call was successful. Your webhook will now be called whenever one of the submitted email addresses is involved in a new Exposure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericAddResponse'
    delete:
      security:
        - enzoic_auth: []
      tags:
        - breachMonitoring
      summary: Delete Exposure alert subscriptions for one or more usernames.
      operationId: deleteBreachMonitoringForUsers
      description: Allows you to delete Exposure alert subscriptions for one or more email addresses.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserBreachMonitoringDeleteBody'
      responses:
        '201':
          description: The call was successful. You will no longer receive alerts for the provided email addresses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericDeleteResponse'
    get:
      security:
        - enzoic_auth: []
      tags:
        - breachMonitoring
      summary: Get Exposure alert subscriptions
      operationId: getBreachMonitoringForUsers
      description: Returns a paginated list of all user-level alert subscriptions for your account.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserBreachMonitoringDeleteBody'
      responses:
        '201':
          description: The call was successful. You will no longer receive alerts for the provided email addresses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericDeleteResponse'
  /breach-monitoring-for-domains:
    post:
      security:
        - enzoic_auth: []
      tags:
        - breachMonitoring
      summary: Create Exposure alert subscriptions for one or more usernames.
      operationId: addBreachMonitoringForDomains
      description: Allows you to setup a new exposure alert subscription for one or more email addresses. For additional privacy and security, emails are submitted as SHA256 hashes.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserBreachMonitoringPostBody'
      responses:
        '201':
          description: The call was successful. Your webhook will now be called whenever one of the submitted email addresses is involved in a new Exposure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericAddResponse'
    delete:
      security:
        - enzoic_auth: []
      tags:
        - breachMonitoring
      summary: Delete Exposure alert subscriptions for one or more usernames.
      operationId: deleteBreachMonitoringForDomains
      description: Allows you to delete Exposure alert subscriptions for one or more email addresses.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UserBreachMonitoringDeleteBody'
      responses:
        '201':
          description: The call was successful. You will no longer receive alerts for the provided email addresses.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenericDeleteResponse'
  /exposures-for-usernames:
    get:
      tags:
        - exposures
      summary: lookup Exposures by usernames
      operationId: exposuresForUsernames
      description: Returns all of the credentials Exposures that have been found for a given user.
      parameters:
        - name: usernames
          description: A list of up to 50 email addresses OR SHA256 hashes of the lowercased email addresses (recommended)
          in: query
          required: true
          example: "usernames=joe@corp.co&usernames=frank@corp.co"
          schema:
            type: array
            items:
              type: string
        - name: includeExposureDetails
          description: If this parameter is specified and non-zero, the results will include the exposure details inline, rather than just the IDs. In this case the exposures array in the response will contain an array of ExposureDetails objects
          in: query
          required: false
          example: 1
          schema:
            type: integer
      responses:
        '200':
          description: The response contains an array of objects, one per username that was passed in. Each object will contain an array of the known Exposures for that user.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ExposuresForUsernamesResponse'
  /exposures-for-domains:
    get:
      tags:
        - exposures
      summary: lookup Exposures for a domain
      operationId: exposuresForDomain
      description: Returns all of the credentials Exposures that have been found for a given domain.
      parameters:
        - name: domain
          description: The domain to return exposures for (e.g. “enzoic.com”)
          in: query
          required: true
          example: corp.co
          schema:
            type: string
        - name: includeExposureDetails
          description: If this parameter is specified and non-zero, the results will include the exposure details inline, rather than just the IDs. In this case the exposures array in the response will contain an array of ExposureDetails objects
          in: query
          required: false
          example: 1
          schema:
            type: integer
        - name: pageSize
          description: The number of results to return in a single call. The default page size is 100 and the maximum is 500.
          in: query
          required: false
          example: 500
          schema:
            type: integer
        - name: pagingToken
          description: For each call to the API, if there are additional pages of results available then a pagingToken will be returned. Pass the pagingToken in via this parameter to retrieve the subsequent page of results. Should be left off for the initial call to the API.
          in: query
          required: false
          example: 598e5b844eb6d82ea07c5783
          schema:
            type: integer
      responses:
        '200':
          description: Exposures for the domain were found and the associated Exposures are in the response body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExposuresForDomainResponse'
        '404':
          description: The domain was not found in Enzoic’s database and has no Exposures associated with it.
  /exposures-for-domain-users:
    get:
      tags:
        - exposures
      summary: lookup Exposures for all users in a domain
      operationId: exposuresForDomainUsers
      description: Returns all of the credentials Exposures that have been found for users in a given domain.
      parameters:
        - name: accountDomain
          description: The domain to return exposures for (e.g. “enzoic.com”)
          in: query
          required: true
          example: corp.co
          schema:
            type: string
        - name: pageSize
          description: The number of results to return in a single call. The default page size is 1000 and the maximum is 1000.
          in: query
          required: false
          example: 500
          schema:
            type: integer
        - name: pagingToken
          description: For each call to the API, if there are additional pages of results available then a pagingToken will be returned. Pass the pagingToken in via this parameter to retrieve the subsequent page of results. Should be left off for the initial call to the API.
          in: query
          required: false
          example: 598e5b844eb6d82ea07c5783
          schema:
            type: integer
      responses:
        '200':
          description: Exposed users for the domain were found and the requested page is in the response body
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExposuresForDomainUsersResponse'
        '404':
          description: The domain was not found in Enzoic’s database and has no exposed users associated with it.
  /exposure-details:
    get:
      tags:
        - exposures
      summary: lookup details for an Exposure
      operationId: exposureDetails
      description: Returns the detailed information for a credentials Exposure. The responses to this call can and should be cached to limit the number of calls made. The Exposure details are not typically expected to change over time, so they can be retained for relatively long periods of time, e.g. for up to 30 days.
      parameters:
        - name: id
          description: The ID of the Exposure
          in: query
          required: true
          example: 57dc11964d6db21300991b78
          schema:
            type: string
      responses:
        '200':
          description: The response body contains the details of the Exposure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExposureDetailsResponse'
        '404':
          description: The requested Exposure was not found
  /passwords:
    post:
      tags:
        - passwords
      summary: check password for compromise
      operationId: passwords
      description: Allows you to check whether a given password is known to be compromised, without needing to pass the exact password hash in. Rather than passing exact hashes of the password to the API, it is only necessary to supply the first 10 hex characters of each hash. A list of candidate hashes will then be returned and can be compared locally with the exact hash to determine if there was a match. This is the recommended approach for new implementations using the Passwords API.
      responses:
        '200':
          description: One or more possible candidate matches were found. The response body contains the candidates. If any of the candidate hashes match the exact hash, this is a compromised password, i.e. a “hacked” password.
          content:
            application/json:
              schema:
                type: object
                items:
                  $ref: '#/components/schemas/PasswordsResponse'
        '404':
          description: No candidate matches were found in the database of compromised passwords – indicates password is not known to be compromised.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PasswordsPostBody'
      security:
        - enzoic_auth: []
components:
  schemas:
    AccountStatusResponse:
      type: object
      properties:
        monthlyAPICallLimit:
          type: integer
          example: 20000
          description: How many calls your account is allowed to make to the Enzoic API every month
        currentAPICallUsage:
          type: integer
          example: 1022
          description: How many calls have been made in the current billing period
        exposureAlertsServiceMonitoredAccountsLimit:
          type: integer
          example: 10
          description: How many email accounts your account is allowed to monitor for new exposures
        exposureAlertsServiceCurrentMonitoredAccounts:
          type: integer
          example: 8
          description: How many email accounts your account is currently monitoring for new exposures
        exposureAlertsServiceMonitoredDomainsLimit:
          type: integer
          example: 1
          description: How many email domains your account is allowed to monitor for new exposures
        exposureAlertsServiceCurrentMonitoredDomains:
          type: integer
          example: 1
          description: How many email domains your account is currently monitoring for new exposures
    AccountUsageResponse:
      type: object
      properties:
        apiCallUsage:
          type: integer
          example: 443644
          description: The total number of API calls made on your account
        passwordAPICalls:
          type: integer
          example: 438364
          description: The number of Passwords API calls made during the specified billing period
        passwordAPIMatches:
          type: integer
          example: 344697
          description: The number of matches returned by the Passwords API during the specified billing period. This can be used as a rough estimate for what percentage of the time a password was rejected.
        credentialsAPICalls:
          type: integer
          example: 120831
          description: The number of Credentials API checks made during the specified billing period
        credentialsAPIMatches:
          type: integer
          example: 10219
          description: The number of matches returned by the Credentials API during the specified billing period. This can be used as a rough estimate for what percentage of the time a set of credentials was found to be compromised.
        exposuresAPICalls:
          type: integer
          example: 23099
          description: The number of Exposures API calls made during the specified billing period
        exposuresAPIMatches:
          type: integer
          example: 17833
          description: The number of matches returned by the Exposures API during the specified billing period.
    UserBreachMonitoringPostBody:
      type: array
      description: An array of SHA256 hashes of the lowercased email addresses you wish to setup breach monitoring for.
      items:
        example: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
        type: string
    UserBreachMonitoringDeleteBody:
      type: array
      description: An array of SHA256 hashes of the lowercased email addresses you wish to remove breach monitoring for.
      items:
        example: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
        type: string
    PasswordsPostBody:
      type: object
      required:
        - partialSHA256
      properties:
        partialSHA256:
          type: string
          example: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
          description: The first 10 hex characters of the SHA-256 hash of the password to be checked. The password should be in UTF-8 encoding prior to hashing.
    ExposuresForUsernamesResponse:
      type: object
      properties:
        username:
          type: string
          example: frank@corp.co
          description: The username for this entry.  Only present if unhashed usernames were provided to the call.
        usernameHash:
          type: string
          example: 51885d3cc1b6f144455e9d25661ca34b9f945b5540b61cb41cf56381950bf50b
          description: The SHA256 hash of the username.  Only present if hashed usernames were provided to the call.
        count:
          type: integer
          example: 1
          description: The number of items in the exposures array.
        exposures:
          type: array
          description: Either an array of Exposure IDs (which can be used to look up additional deails with the /exposure-details call) or if includeExposureDetails was specified in the query string, an array of Exposure details objects.
          items:
            $ref: '#/components/schemas/ExposureDetailsResponse'
    ExposuresForDomainResponse:
      type: object
      properties:
        count:
          type: integer
          example: 1
          description: The number of items in the exposures array
        pagingToken:
          type: string
          example: 598e5b844eb6d82ea07c5783
          description: Present when there are additional pages of results available. Pass this token in on a subsequent call to fetch the next page of results.
        exposures:
          type: array
          items:
            $ref: '#/components/schemas/ExposureDetailsResponse'
          description: Either an array of Exposure IDs (which can be used to look up additional deails with the /exposure-details call) or if includeExposureDetails was specified in the query string, an array of Exposure details objects.
    ExposuresForDomainUsersResponse:
      type: object
      properties:
        count:
          type: integer
          example: 1
          description: The total number of users exposed for the domain.  This is across all pages.
        pagingToken:
          type: string
          example: 598e5b844eb6d82ea07c5783
          description: Present when there are additional pages of results available. Pass this token in on a subsequent call to fetch the next page of results.
        users:
          type: array
          description: Either an array of Exposure IDs (which can be used to look up additional deails with the /exposure-details call) or if includeExposureDetails was specified in the query string, an array of Exposure details objects.
          items:
            type: object
            properties:
              username:
                type: string
                example: sample@email.tst
                description: The email address of the user who was exposed
              exposures:
                type: array
                description: An array of Exposure IDs. Can be used with the Exposure Details call to retrieve additional info.
                items:
                  type: string
                  example: 57dc11964d6db21300991b78
    ExposureDetailsResponse:
      type: object
      properties:
        id:
          type: string
          example: 57dc11964d6db21300991b78
          description: The unique ID of the Exposure.
        title:
          type: string
          example: funsurveys.net
          description: Title of the exposure – for breaches, the domain of the origin site. For exposures where it’s not possible to determine the origin site, we provide the title as Unknown source and include the date it was found and added to our database in parentheses.
        entries:
          type: integer
          example: 5123
          description: The number of credentials found in the exposure
        date:
          type: string
          format: date
          example: 2015-05-01T00:00:00.000Z
          description: |
            The date the exposure occurred, as much as is known.  The value is as follows:
            - null if the date is not known
            - Month and day set to December 31st, if only the year is known (e.g. “2015-12-31” if Exposure date was sometime in 2015)
            - Day set to the first of the month if only the month is known (e.g. “2015-06-01” if Exposure date was sometime in June 2015)
            - Otherwise, exact date if exact date is known, including time
        category:
          type: string
          example: Surveys
          description: A category for the origin website, if the exposure was a data breach.
        passwordType:
          type: string
          example: Cleartext
          description: The format of the passwords in the Exposure, e.g. “Cleartext”, “MD5”, “BCrypt”, etc.
        exposedData:
          type: array
          example: ["Emails", "Passwords"]
          items:
            type: string
          description: The types of user data which were present in the Exposure, e.g. “Emails”, “Passwords”, “Physical Addresses”, “Phone Numbers”, etc.
        dateAdded:
          type: string
          format: date
          example: 2016-09-16T15:36:54.000Z
          description: The date the Exposure was found and added to the Enzoic database.
        sourceURLs:
          type: array
          items:
            type: string
          example: ["https://www.someplace.com"]
          description: An array of URLs the data was found at. Only present for some types of Exposures, like when the source was a paste site.
        domainsAffected:
          type: integer
          example: 683
          description: The number of unique email address domains in this Exposure. So, for instance, if the Exposure only contained “gmail.com” and “yahoo.com” email addresses, this number would be 2.
    PasswordsResponse:
      type: object
      properties:
        candidates:
          type: array
          items:
            type: object
            properties:
              sha256:
                type: string
                example: 9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08
                description:
                  The SHA256 hash of this match candidate. Check this value against the full MD5 hash of the password you are checking to determine if it is a match.
              revealedInExposure:
                type: boolean
                example: true
                description: Whether the password was exposed in a known data Exposure. If this value is false, the password was found in common password cracking dictionaries, but has not been directly exposed as a user password in a data breach or other Exposure.
              exposureCount:
                type: integer
                example: 10
                description: The total number of exposures this password has appeared in. While it’s a bad idea to ever use a password that has been publicly exposed even a single time, this number can be used to determine how common a password is and how often it has been exposed.
    GenericAddResponse:
      type: object
      properties:
        added:
          type: integer
          example: 1
          description: The number of new alert subscriptions created.
        alreadyExisted:
          type: integer
          example: 0
          description: The number of alert subscriptions which already existed.
    GenericDeleteResponse:
      type: object
      properties:
        deleted:
          type: integer
          example: 1
          description: The number of alert subscriptions deleted.
        notFound:
          type: integer
          example: 0
          description: The number of provided email hashes which were not found in the alert subscriptions table.
  securitySchemes:
    enzoic_auth:
      type: http
      scheme: basic
      description: The username is your API key and the password is your API secret.
