Create a subscription:

`POST /subscriptions`

Create a subscription to define a streaming channel that sends data from devices in the account to an endpoint defined in a target resource.

Uses and Requirements

You must create a target before creating the corresponding subscription.

Different event types

If the ThingSpace client on a device supports it, a device can send different types of event data, such as sensor readings, diagnostic information, security information, and configuration information. You can set the streamkind value in a subscription to define which type of event that subscription will handle. You can create different subscriptions that each handle different types of events. Note that with account-level streaming, you cannot create two subscriptions that have the same streamkind.

Request Components

HTTP Request

`POST https://thingspace.verizon.com/api/cc/v1/subscriptions`

Resource Path and Query Parameters

None.

Header Parameters

The request header must contain a current ThingSpace authorization token and a current VZ-M2M session token, and must set the content-type to JSON.

Property Name	Data Type	Description
Authorization required	string	HTTP Authorization request header containing a valid ThingSpace Bearer token.
VZ-M2M-Token required	string	A valid session token returned by a Connectivity Management API POST /session/login request using the account’s UWS credentials.
Content-Type required	string	Must be `application/json`.

Request Body

The request body provides the details of the subscription that you want to create.

Property Name	Data Type	Description
accountidentifier required	JSON object	The ID of the authenticating billing account, in the format `{"billingaccountid":"1234567890-12345"}`.
description optional	string	Descriptive information about the subscription.
disabled optional	boolean	Enable or disable the subscription. A disabled subscription will not send any data.
email optional	string	The address to which any error reports should be delivered.
filter optional	string	String containing a $filter object with a property and value to filter out non-matching events.
name optional	string	Name of the subscription.
streamkind required	string	The type of event data to send via this subscription. This will be `ts.event` in most cases. Other event types are `ts.event.diagnostics` for device diagnostic data, `ts.event.configuration` for device configuration events, or `ts.event.security`. Note that the device ThingSpace client must support sending specific event types for anything other than `ts.event`.
targetid required	string, UUID	The ID of the target resource to be used when dispatching events. The corresponding target should have a “stream” addressscheme
allowaggregation required	boolean	Setting this value to "false" prevents the data returned from being aggregated and makes the data easier to parse

Example Requests

Create a subscription for streaming

curl -X POST https://thingspace.verizon.com/api/cc/v1/subscriptions \
  -H 'Authorization: Bearer {bearer token}' \
  -H 'VZ-M2M-Token: {session token}' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountidentifier": {"billingaccountid":"1223334444-00001"},
    "billingaccountid":"1223334444-00001"
    "allowaggregation": false,
    "name": "Account subscription 1",
    "targetid":"{target ID}",
    "streamkind":"ts.event",
    "email":"me@mycompany.com"
  }'

Success Responses

Status 200

A success response includes the full subscription resource definition.

Property Name	Data Type	Description
configurationfailures	integer	The number of streaming failures due to faulty configuration.
createdon	string, date-time	The date the resource was created.
delegateid	string	Not currently used.
description	string	Description of the subscription.
disabled	boolean	Whether the subscription is currently sending data.
email	string	The address to which any error reports should be delivered.
filter	string	Filter for events.
id	string, UUID	ThingSpace unique ID for the subscription that was created.
kind	string	Identifies the resource kind.
laststreamingstatus	string	Success or fail
laststreamingtime	string, date-time	The date and time that the last stream send was attempted.
lastupdated	string, date-time	The date the resource was last updated.
name	string	Name of the subscription.
networkfailures	integer	The number of failures due to network problems.
streamfailures	integer
streamkind	string, enum	The event type that will be sent in the data stream.
targetid	string	Target to be used for dispatching events.
targettype	string
version	string, UUID	Version of the underlying schema resource.
versionid	string, UUID	The version of the resource.

Example Success Response

{
  "configurationfailures": 0,
  "createdon": "2018-12-21T05:05:02.134Z",
  "delegateid": "00000000-0000-0000-0000-000000000000",
  "id": "d8c145dd-6948-67ec-ed9b-6a298806bb4a",
  "kind": "ts.subscription",
  "laststreamingstatus": "",
  "laststreamingtime": "0001-01-01T00:00:00Z",
  "lastupdated": "2018-12-21T05:22:12.178Z",
  "networkfailures": 0,
  "streamfailures": 0,
  "streamkind": "ts.event",
  "targetid": "4e211a0e-e39d-6c32-e15b-d6f07f9e2ec8",
  "version": "1.0",
  "versionid": "5ed6063f-04e0-11e9-8279-02420a5e1b0b"
}

Failure Responses

Status 4xx

All error messages are returned in this format:

{
  "error": "error code string",
  "error_description": "error message string",
  "cause": "further explanation"
}

Error codes and messages are listed on the Error Messages page, along with explanations and suggestions for corrective actions.