Mason Docs

Connectivity API

All requests to connectivity api's must be authenticated and have the scope CONNECT:READ, unless otherwise noted. Each response body is returned as json.


GET Subscription

https://api.bymason.com/v1/default/subscription

Subscriptions represent the connectivity billing model for a fleet of sims.

There are two kinds of subscriptions:

  1. Data pool
  2. Pay as you go

By default...

  • All subscriptions are a data pool subscription
  • A subscription typeSpecific.target value is calculated using a 500 Mb multiplier per provisioned device

Subscriptions do not include billing rates, only the amount of data available to a fleet.

Required API key scope(s)

  • connect:read

For more information on scoping API keys, visit our guide for creating API keys

Sample request(s)

$ curl -H "Authorization: basic $API_KEY" api.bymason.com/v1/default/subscription

Response body (JSON)

NameTypeDescription
accountIDstringThe account the subscription belongs to
typestringThe kind of subscription. Will be one of device_data_pool | pay_as_you_go
typeSpecificobjectSubscription type specific information. This value is dependent on the type of subscription. For device_data_pool subscriptions, this value represents the number of bytes allowed per month before overage charges incur. For pay_as_you_go, this value represents the target amount of bytes per month the fleet should use.

Data pool subscription type

The data pool subscription allows customers to choose how much data they can use before they incur overage charges. This amount is calculated by specifying how much data each device can contribute to the overall pool of data. Any device in the fleet can use data from the pool, but if the fleet goes over, then overage charges incur.

Sample json

{
  "typeSpecific": {
      "value": 5000000,
  },
  "type": "device_data_pool",
}

Pay as you go subscription type

The pay as you go subscription allows customers to have a flat rate for all of their data, no matter how much is used.

Sample json

{
  "typeSpecific": {
      "target": 5000000,
  }
  "type": "pay_as_you_go",
  "accountID": "accountID"
}

GET Data cap

Data caps represent the amount of data a fleet can use in a given month.

https://api.bymason.com/v1/default/data/caps

Data caps are calculated differently based on subscription model.

Subscription typeData cap calculation
device_data_poolThe cap is determined by the number of provisioned devices multiplied by the amount of data per device
pay_as_you_goThe cap is defined by the customer

For the device_data_pool subscription, the softcap is the amount of data a fleet can use before higher rates apply. The target softcap for pay_as_you_go is user defined as the amount the customer would like to get to, but not go over. pay_as_you_go is a flat rate per Mb, regardless of how much data is used.

Data caps do not include the rates at which a fleet is billed.

Required API key scope(s)

  • connect:read

For more information on scoping API keys, visit our guide for creating API keys

Query parameters

NameTypeDescription
date (optional)stringRFC339 formatted string, representing date to retrieve data cap

Sample request(s)

$ curl -X GET -H "Authorization: basic $API_KEY" https://api.masonamerica.net/v1/default/data/caps -d date="2020-07-01T00:00:00Z"

Response status codes

Status codeDescription
200Success
400The request was malformed
401The user is not authenticated or is not authorized to make the request
404The account does not have a datacap
500There was an internal server error

Response body (JSON)

NameTypeDescription
datestringThe month the data cap is active represented as an RFC339 formatted date
softcapuint64The amount of data allowed by the fleet
subscriptionSubscriptionThe subscription the cap was calculated for
unitsstringThe unit used by the softcap. Will be one of gigabytes | megabytes | kilobytes | bytes

Sample JSON

{
  "date": "2020-07-01T00:00:00Z",
  "softCap": 100000,
  "units":"bytes"
}