​
Overview

When talking about the Data Structure of AbuseHQ, we refer to the data that can be influenced by you and will, in turn, influence your setup and capabilities down the line. Don’t worry—most things can be adjusted later. Nevertheless, it’s worth taking a moment upfront to plan. AbuseHQ has four hierarchy layers:
  • Subscriber
  • Contract (optional)
  • Case
  • Event
These layers relate to one another in a structured hierarchy, as shown in the graphic (not included here).

​
Event

When an abuse report comes in—such as an ARF feedback loop or a bulk report from Shadowserver—it can lead to one or many Events. AbuseHQ automatically splits these up correctly, so you always have a clear and consistent view of what’s happening.

​
Case

A Case is a container for related Events. Whether a new Case is created or an Event is attached to an existing Case is determined by:
  • Case Creation Rules
  • Case Groups
  • Subscriber Resolution
AbuseHQ Agents and Automation primarily operate on the Case level in daily workflows.

​
Contract (Optional)

The Contract layer is optional and flexible. You may use it in some situations and skip it in others. While the term “Contract” is used for naming consistency, this layer could also represent:
  • A campaign (e.g., for an Email Service Provider)
  • A sub-feature within a contract
  • Any other logical grouping relevant to your use case
💬 Not sure if you should use this layer? Reach out via chat or email [email protected] for real-world examples from other customers.

​
Subscriber

At the top of the hierarchy is the Subscriber. You might call them customers or clients—AbuseHQ calls them Subscribers.
Subscriber information is required.
Without it, no Cases will be created, and incoming emails will be discarded into the mailbox.

​
Subscriber Resolution

One of the most essential parts of AbuseHQ is the Subscriber Resolver. This component ensures that:
  • Every Event is associated with the correct Subscriber
  • (Optionally) Events are mapped to the correct Contract
  • Events are attached to the correct Case
If an Event can’t be resolved, it won’t trigger a Case or attach to one. Why is this important? Because AbuseHQ’s goal is to help solve your customers’ problems, and without knowing who the Subscriber is, that’s impossible.
📌 Example: As a Cable Provider, you may only know that an IP address sent spam at a given time. The Subscriber Resolver maps that IP and timestamp to the correct Subscriber ID.

​
Enriching Subscriber & Contract Data

Being able to resolve Events into Cases and assign them to the right Subscriber and Contract is powerful. But sometimes you need additional data to influence your workflows. For example:
  • Is the Subscriber a VIP? Treat their Cases with higher priority.
  • What’s the creation date of the Contract?
  • What’s the Subscriber’s email address (for use in the AbuseHQ Bulk Mailer)?
You can enrich this data via API.

​
Example JSON

{
  "subscriber": {
    "id": "<subscriber_id>",
    "resolver_data": {
      "<subscriber_key1>": "<subscriber_value1>",
      "<subscriber_key2>": "<subscriber_value2>"
    }
  },
  "contract": {
    "id": "<contractid>",
    "resolver_data": {
      "<contract_key1>": "<contract_value1>",
      "<contract_key2>": "<contract_value2>"
    }
  }
}
This information can be provided using the API Subscriber Resolver or the X-Header Resolver.