👋 How can we help you?

Subscriber data model

Data structure of AbuseHQ can be influenced by you and will impact your setup and capabilities down the line.

Last updated on Invalid Date


When talking about the Data Structure of AbuseHQ, we think of the data that can be influenced by you and will influence your setup and your capabilities down the line. Don't worry, most of the things can be adjusted and changed afterward, nevertheless it's never wrong taking a minute upfront and make a plan.

AbuseHQ knows four hierarchy layers consisting of Subscriber, Contract, Case, and Event which stand in a relationship as seen in the graphic.


Let's look at each of them from the bottom up:


If you think of incoming Abuse Reports, like an ARF Feedbackloop or a Bulk Report by Shadowserver, an incoming Abuse Report will lead to at least one but can also result in some individual cases to hundreds or thousands of Events. AbuseHQ takes care about splitting them up correctly, so you always have a similar perception of what is happening.



A Case is the next higher layer, that will function as a kind of container for Events. Case Creation Rules, including Case Groups and specific Subscriber Resolving, will determine if an Event will be responsible for the creation of new Case or will be attached to Cases. In the daily work Agents and also AbuseHQ Automation will mainly work on Cases.


Contract (optional)

A Contract is an optional layer that you can decide to use or not to use. It is even possible to use it in a few and not to use it in a few other cases. We used the word Contract since it makes most syntactical sense, but it is just another layer, that does not have to reflect a contract but can also reflect for example a Campaign in case of an E-Mail Service Provider, or also a Sub-Feature within a contract. This depends entirely on you and your use case. If you are unsure, please feel free to talk to us, and we will be happy to help you with examples from other customers.



Finally and therefore the highest layer is the Subscriber itself. We call them Subscriber, you may call them customers or clients as well. The Subscriber is mandatory information. Without Subscriber information, there will be no Case created and incoming emails will end up in the mailbox.


Subscriber Resolution

One of the essential things in AbuseHQ is the Subscriber Resolver. The Subscriber Resolver will take care that all events will end up in the right Cases associated with (the correct Contract and) the correct Subscriber. If an Events can't be resolved, it will not end up creating a Case nor will it be attached to a Case.

This is important because we are trying to solve our issues, by solving a customers issues and not knowing who the Subscriber is, makes it impossible.Think about it from a Cable Provider point of view where we only know which IP address at what time was sending the Spam Message. Subscriber Resolving will make sure we can resolve the IP and Date to a Subscriber ID.

Now, aggregating incoming events already in Cases and correctly allocating those Cases in the correct Contracts and Subscribers are already pretty helpful. In some cases, you want to add more detail about a Contract or a Subscriber to AbuseHQ to alter your decision based on additional information.

Such information can, for example, be as simple as if the Subscriber has VIP status. Because if he is a VIP, you'll handle his Cases differently. It could also be the create date of Contract/Subscriber or his email address to send messages directly from AbuseHQ Bulk Mailer.


An example JSON looks like this:

    "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 type of information can be made available via API Subscriber Resolver and the X-Header Resolver.

Did this answer your question?