# Holehe Standardized Result Dictionary: The 7 Fields Every OSINT Module Returns

> Discover the 7 essential fields in the Holehe standardized result dictionary. Learn how these fields ensure uniform email-checking results across thousands of services for your OSINT modules.

- Repository: [Palenath/holehe](https://github.com/megadose/holehe)
- Tags: api-reference
- Published: 2026-08-24

---

**The Holehe standardized result dictionary contains seven required keys—`domain`, `exists`, `emailrecovery`, `phoneNumber`, `others`, `rateLimit`, and `error`—that enable the core printer to process email-checking results from thousands of services uniformly.**

The `megadose/holehe` repository enforces a strict data contract between its modules and central output logic. Every OSINT module returns this standardized dictionary to [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py), ensuring consistent formatting regardless of which website or service was queried. Understanding these seven fields is essential for developers extending Holehe with custom modules or parsing its JSON output programmatically.

## The Seven Required Dictionary Fields

Every module in the `holehe/modules/` directory constructs a dictionary with identical top-level keys. The core printer expects this exact structure, as implemented in the `print_result` function at lines 123–144 of [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py).

### Domain and Existence Indicators

**`domain`** stores the target website or service as a string (e.g., `"facebook.com"`), identifying which service was queried. **`exists`** is a boolean flag indicating whether the supplied email address is registered on that service—`True` confirms an account exists, while `False` indicates it does not.

### Recovery and Contact Information

**`emailrecovery`** captures any password-reset hints exposed by the service, typically returning a string like `"p***@example.com"` or `None` if no hint is available. **`phoneNumber`** stores partial or full phone numbers leaked by the service during the check, also returning a string or `None` when no data is exposed.

### Extensible Metadata and Error States

**`others`** provides a free-form dictionary for additional scraped data—such as full names, account creation dates, or profile URLs—that does not fit the standard schema. **`rateLimit`** is a boolean set to `True` when the service enforces rate limiting and the check must be skipped. **`error`** signals unexpected failures like network timeouts or parsing exceptions, returning `True` when the module encounters an exception rather than a valid response.

## How the Core Printer Processes the Dictionary

The `print_result` function in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) evaluates these fields in a specific priority order to determine output formatting:

1. **Rate Limit Check**: `if results["rateLimit"]` triggers first, handling services that blocked the request due to throttling.
2. **Error Handling**: `elif "error" in results.keys() and results["error"]` catches unexpected exceptions and prints generic error messages.
3. **Non-Existence**: `elif results["exists"] == False` reports that the email is not registered on the service.
4. **Successful Matches**: `elif results["exists"] == True` builds the success line, conditionally appending `emailrecovery`, `phoneNumber`, and values from the `others` dictionary.

This branching logic ensures that `rateLimit` and `error` states take precedence over existence checks, preventing false negatives when services block requests.

## Implementing the Contract in Custom Modules

When developing new modules for the `holehe/modules/` directory, you must return the complete dictionary structure even for failed checks. The core printer relies on every key being present to avoid `KeyError` exceptions during output generation.

```python

# Example module implementation from holehe/modules/social_media/facebook.py

def check_facebook(email, client, out):
    try:
        # ... HTTP request logic ...

        return {
            "domain": "facebook.com",
            "exists": True,
            "emailrecovery": "j***@gmail.com",
            "phoneNumber": None,
            "others": {"FullName": "John Doe", "ProfileURL": "..."},
            "rateLimit": False,
            "error": False,
        }
    except Exception:
        return {
            "domain": "facebook.com",
            "exists": False,
            "emailrecovery": None,
            "phoneNumber": None,
            "others": None,
            "rateLimit": False,
            "error": True,
        }

```

The `out` parameter in modern Holehe versions acts as a list append function, but the underlying dictionary structure remains identical. Always populate all seven keys to maintain compatibility with the printer logic in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py).

## Summary

- **Seven mandatory keys**: `domain`, `exists`, `emailrecovery`, `phoneNumber`, `others`, `rateLimit`, and `error` form the standardized contract.
- **Core processing**: The printer in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) (lines 123–144) evaluates `rateLimit` and `error` before checking `exists` to ensure accurate status reporting.
- **Extensibility**: The `others` dictionary allows modules to return service-specific data without breaking the standard schema.
- **Consistency**: Every module from `holehe/modules/social_media/` to `holehe/modules/shopping/` must return this identical structure for the CLI and JSON output to function correctly.

## Frequently Asked Questions

### What happens if a Holehe module omits one of the required dictionary keys?

The core printer in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) will raise a `KeyError` when attempting to access the missing field, typically during the conditional checks at lines 123–144. All seven keys must be present in every return statement, even when their values are `None` or `False`.

### Can the `others` dictionary contain nested data structures?

Yes, the `others` field accepts any valid Python dictionary, including nested objects, lists, or additional metadata. The core printer stringifies these values when displaying results, making it suitable for complex data like profile timestamps, avatar URLs, or location histories scraped by individual modules.

### How does Holehe handle rate limiting differently from errors?

When `rateLimit` is `True`, the printer in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) reports that the service blocked the request due to throttling, distinguishing it from technical failures. The `error` flag indicates unexpected exceptions like network timeouts or HTML parsing failures, while `rateLimit` specifically signals HTTP 429 responses or CAPTCHA challenges that prevent the check from completing.

### Is the standardized dictionary format documented in the Holehe source code?

The schema is enforced through the `print_result` function implementation in [`holehe/core.py`](https://github.com/megadose/holehe/blob/main/holehe/core.py) rather than formal type hints. Developers should examine lines 123–144 of that file and reference existing modules in [`holehe/modules/social_media/facebook.py`](https://github.com/megadose/holehe/blob/main/holehe/modules/social_media/facebook.py) to understand the expected return structure for the `megadose/holehe` codebase.