Per REST API v1

Quick start

Get started with Per quickly

Create an API token

To interact with the API you’ll need an API token, which you can create on the API tokens page. Enter a token description—for example, if you have a mobile app and a web app, you might want to have a different token for each. Select Activity as your token scope. (You’ll use a reporting token only when you need to pull reports about your users.)

Save your new token in the environment variable PER_ACTIVITY_TOKEN.

Activity type

Create your activity type, which is your definition of what user activity you are measuring, from the Activity types page. Add your activity type name, and click “+ Create Activity Type”. If you aren’t sure what to name your activity type, we suggest “active users”.

Save the ID of your new activity type in the environment variable ACTIVITY_TYPE_ID.

Send activity

Decide what activity means to you. Basically, what set of user behavior will cause one of your users to be set to active. We recommend connecting it to some core important user activity, but it’s up to you. You will call our activity.set API whenever a user does whatever this is. If you aren’t sure, try calling activity.set whenever a user logs in.

If you have an opaque user ID and/or customer/organization/etc ID, you should use that. We prefer it if you use something that means something to you, but doesn’t mean anything to us. For example, “J21H391” could be a good user ID if you store that for a person, but “bob@example.com” is probably not. The billing ID is how Per groups your users into your billable organizations. For example, if you have 10 paying customers, each of whom is a company with 100 users, you should report each user with a unique user ID, and have a different billing ID for each of the 10 customers. Sending this with your activity event will make your reports specific to your users and their organizations.

const request = require('request-promise');
async function sendActivity() {
  try {
    const response = await request({
      uri: 'https://api.useper.com/activities.add',
      qs: {
        billingId: 'GROUP_A',
        userId: 'USER_ID_1',
        activityTypeId: process.env.ACTIVITY_TYPE_ID
      },
      headers: {
        Authorization: `Bearer ${process.env.PER_ACTIVITY_TOKEN}`
      },
      json: true
    });
    // response.ok should be true, response.result.id has a transaction ID
    console.log(JSON.stringify(response));
  } catch (err) {
    console.error(err);
  }
}
curl -v -X GET -H \
 "Authorization: Bearer $PER_ACTIVITY_TOKEN" \
 "https://api.useper.com/activities.add?userId=USER_ID_1\&billingId=GROUP_A\&activityTypeId=$ACTIVITY_TYPE_ID"

Get reports

To interact with the reporting API you’ll need a different API token, which you can get from the API tokens page. Enter a token description—for example, if you have a mobile app and a web app, you might want to have a different token for each. Select Reporting as your token scope. For this example, save this token as an environment variable named PER_REPORTING_TOKEN.

Because this reporting token allows access to your customer account, be sure to keep it safe. Don’t put it in any of your user-facing code.

When it’s time to bill your customers, call the reports.get API. By default, this API will return the previous month’s data, but you can specify start and end parameters to get a report covering the window of your choosing, subject to your plan limits. See the reports.get API documentation for full details.

const request = require('request-promise');
async function getReport() {
  try {
    const response = await request({
      uri: 'https://api.useper.com/reports.get?start=2019-11-11T15:40:30.968Z&end=2019-11-13T15:40:30.968Z',
      headers: {
        Authorization: `Bearer ${process.env.PER_REPORTING_TOKEN}`
      },
      json: true
    });
    // response.ok should be true, response.result contains the report data
    console.log(JSON.stringify(response));
  } catch (err) {
    console.error(err);
  }
}
curl -v -X GET -H \
 "Authorization: Bearer $PER_REPORTING_TOKEN" \
 "https://api.useper.com/reports.get?start=2019-11-11T15:40:30.968Z&end=2019-11-13T15:40:30.968Z"