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:

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 JS

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

Response body (JSON)

Name	Type	Description
accountID	string	The account the subscription belongs to
type	string	The kind of subscription. Will be one of `device_data_pool` \| `pay_as_you_go`
typeSpecific	object	Subscription 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 type	Data cap calculation
`device_data_pool`	The cap is determined by the number of provisioned devices multiplied by the amount of data per device
`pay_as_you_go`	The 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

Name	Type	Description
`date` (optional)	string	RFC339 formatted string, representing date to retrieve data cap

Sample request(s)

CURL JS

$ 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 code | Description | |:---|:---|:---| | 200 | Success | | 400 | The request was malformed | | 401 | The user is not authenticated or is not authorized to make the request | | 404 | The account does not have a datacap | | 500 | There was an internal server error |

Response body (JSON)

Name	Type	Description
date	string	The month the data cap is active represented as an RFC339 formatted date
softcap	uint64	The amount of data allowed by the fleet
subscription	Subscription	The subscription the cap was calculated for
units	string	The 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"
}