AbuseHQ

support people
Welcome to the AbuseHQ Documentation, where you'll
find comprehensive guides and documentation to help you get started
working with AbuseHQ as quickly as possible, as well as advanced
know-how about how to get the most out of AbuseHQ.

Get Started    

Subscriber Data Model

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, never the less 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:

Event:

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.

Case:

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.

Subscriber:

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.


Subscriber Data Model


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.