Per REST API v1

Concepts and terminology

Per is about counting activity and usage. You tell us about any activity on which you want to bill your users, and then ask us for usage totals when you're ready to bill your users.

Because Per touches both your company and also your company’s users, normally simple terms like “user” could be ambiguous: when we say “users”, are we talking about you, or about your users? Both internally and publicly we have chosen very specific terminology in order to help with clarity, and we try to be extraordinarily consistent with its usage. If you have any questions, please don’t hesitate to reach out and ask [link needed].

Customer

You are a customer. That is, a customer is any person or company directly registered with Per and integrating with our activity and reporting endpoints.

Application

Your product/application is an application. At present, there is a one-to-one correlation between a customer and an application.

User

Your application’s users are users. We deliberately chose this definition for the term “user” to reduce confusion for our customers, most of whom already use the term “user” within their application. This way, when we say “users”, and you say “users”, we’re referring to the same concept.

Activity

Any time your application’s users perform an action you want to consider as “active”, you call Per’s Activity API.

Billing ID / User ID

When sending activity to Per, you are required to send a “billing ID” and a “user ID”. Both of these are defined by you in order to properly scope your application’s activity. Per has no expectations over to format or content of these IDs, other than to use them for grouping and uniqueness.

For example, let’s say your application is a messaging application, and you have users from two separate companies, “Awesome Company” and “Brilliant Business”. Ultimately, you need to be able to charge these companies separately, based on the activity of the users from each. You likely already have an internal representation for the companies and for users, but let’s assume that you simply use the companies’ names and an opaque user ID for that purpose. This might result in activity events like:

Billing IDUser ID
Awesome CompanyNR12FA
Brilliant BusinessKF94HA
Awesome CompanyOR934L4
Brilliant BusinessKF94HA

Based on this information, Per can determine that there were two unique users from Awesome Company (NR12FA and OR934L4), with one activity each, and one unique user from Brilliant Business (KF94HA), with two instances of activity recorded.