Overview

Codes are a hierarchical categorization system which may be applied to a variety of Entities.

There are two types of Codes: Source Codes, and Tags. Source Codes are used to indicate the effort or activity which caused an Entity to be added to the database; at most one Source Code may be applied to any given Entity. Tags may be used to indicate a variety of properties about an Entity; any number of Tags may be applied to a given Entity.

Source Codes may only be applied to the following Entities only: People, Events, and Contributions. Tags may be applied to People, Events, and other Entities. The list of Entities to which a Tag may be applied depends on the context of the API key in use; the GET /entities/supportedEntities route may be used to determine which Entities may have Tags applied for an given API key.

The hierarchical nature of Codes makes it possible for a single Code to convey several pieces of information at once. For example, you could categorize a variety of marketing campaigns in a hierarchical manner:

  • Digital Ads
    • Facebook
      • Jan 2017
      • Feb 2017
      • Valentine’s Day Promotion
    • Twitter
      • Promoted tweets
  • Bulk mail
    • Post cards
    • Newsletter

If the Promoted tweets Code is applied to a Contribution, that conveys three pieces of information: that the Contribution came from Digital Ads, and more specifically from Twitter, and finally that it came from Promoted tweets. This hierarchy allows a single Code to carry a significant amount of information because each Code can have a parent (e.g., the parent of Promoted tweets is Twitter.) As is demonstrated in the above example, Codes need not have the same number of parents, grand-parents, etc. Promoted tweets is three levels deep whereas Post cards is only two levels deep.

Codes have another helpful attribute called applicability. In some cases, a Code’s parent may be able to stand on its own. For example, if Post cards is too specific of an attribute for certain kinds of Contributions, Bulk mail may suffice. In this case, it’d make sense to allow Bulk mail to be Applicable.

In the case of Digital Ads, you may decide that your classifications are complete enough that you do not want to simply classify something as Twitter. In that case, you’d make Twitter be Searchable Only. This means that you can find Contributions marked with any Twitter promotion, but no Contribution can be just from Twitter only.

Use the Codes endpoint to create, update, and delete Tags and Source Codes, as well as to discover existing Tags and Source Codes, and to retrieve metadata about each. You can perform these operations on a single code or on a batch of codes.

Codes are applied using the appropriate endpoint for the supported entity to which the Code is being applied. For example, to apply Codes to a Person, use POST /people/{vanId}/codes.