Create a Target

Create a target:
POST /targets

Define a target to receive data streams, alerts, or callbacks. After creating the target resource, use its ID in a subscription to set up a data stream.

See also:
Create a subscription
Query targets

Uses and Requirements

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/cc/v1/targets

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 target 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"}.
address
optional
string The endpoint for notifications or data streams. The format depends on the selected addressscheme.
  • streamrest requires a host:port value
  • streamawsiot requres a valid ARN
addressscheme
optional
string, enum The transport format. Valid values are:
  • streamawsiot - streamed data to an AWS account
  • streamrest - streamed REST data to a defined endpoint
description
optional
string Descriptive information about the target.
externalid
required for AWS
string Security identification string created by a POST /targets/actions/newextid request.
name
optional
string Name of the target.
region
required for AWS
string AWS region value.
key1
required for Target with oAuth 2.0
string oAuth 2.0 bearer token.
oauth
required for Target with oAuth 2.0
JSON OAUTH 2 token and refresh token for TS to stream events to Target in the format {"oauth":{"body": {"grant_type":"refresh_token","refresh_token":"qfeqVjZTYzMmUtZWMzZqfq4ZDUtNzFhZWVkYTlmMjk1","scope":"option to provide scope"}, "headers": {"Authorization":"Basic RGFrqewfq2xpZW50QXBwVjI6YzM5YjqfqmI2LMI2MWPtNDRlZTQ5MmM1YTRk","Content-Type":"application/x-www-form-urlencoded"},"host":{"hostandpath":"https:// myhost.com:1825","version":"1.0"}}}

Example Requests

Create a target for AWS streaming

curl -X POST https://thingspace.verizon.com/api/cc/v1/targets \
  -H 'Authorization: Bearer 225aec324bb619d10101ca905fd2479e' \
  -H 'VZ-M2M-Token: 85d73f80-3127-4d04-81ae-82497cc557dd' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountidentifier": {"billingaccountid":"1223334444-00001"},
    "name": "AWS Target",
    "addressscheme":"streamawsiot",
    "address":"arn:aws:iam::252156542978:role/ThingSpace",
    "externalid":"lJZnih8BfqsosZrEEkfPuR3aGOk2i-HIr6tXN275ioJF6bezIrQB9EbzpTRep8J7RmV7QH==",
    "region": "us-east-1"
}'

Create a target for host:port streaming

curl -X POST https://thingspace.verizon.com/api/cc/v1/targets \
  -H 'Authorization: Bearer 225aec324bb619d10101ca905fd2479e' \
  -H 'VZ-M2M-Token: 85d73f80-3127-4d04-81ae-82497cc557dd' \
  -H 'Content-Type: application/json' \
  -d '{
    "accountidentifier": {"billingaccountid":"1223334444-00001"},
    "name": "ThingSpace stream target",
    "addressscheme":"streamrest",
    "address":"https://myhost.com:1825"
}'

Create a target for host:port streaming with OAuth 2.0 authorization:

curl -X POST \https://thingspace.verizon.com/api/cc/v1/targets \ 
  -H 'authorization: Bearer 225aec324bb619d10101ca905fd2479e' \ 
  -H 'content-type: application/json' \ 
  -H 'vz-m2m-token: 85d73f80-3127-4d04-81ae-82497cc557dd' \ 
  -d '{"accountidentifier":{"billingaccountid": "1223334444-00001"},
    "address":"https://myhost.com:1825",
    "addressscheme":"streamrest",
    "key1":"Bearer MmY3ZefqefqDk4Ni00MzZmLWJkYzgtYTI4qfqBjNTc2",
    "kind":"ts.target",
    "oauth":{
      "body": {
        "grant_type":"refresh_token",
        "refresh_token":"qfeqVjZTYzMmUtZWMzZqfq4ZDUtNzFhZWVkYTlmMjk1",
        "headers":{
          "Authorization":"Basic RGFrqewfq2xpZW50QXBwVjI6YzM5YjqfqmI2LWI2MWQtNDRlZTQ5MmM1YTRk",
          "Content-Type":"application/x-www-form-urlencoded"
        },
        "host":{
          "hostandpath":"https:// myhost.com:1825"
        }
      },
      "version":"1.0"
    }'

Success Responses

Status 200

A success response includes the full target resource definition.

Property Name Data Type Description
address string The endpoint for data streams.
addressscheme string The transport format.
createdon string, date-time The date the resource was created.
description string Description of the target.
externalid string Security identification string.
id string, UUID ThingSpace unique ID for the target that was created.
kind string Identifies the resource kind. Targets are ts.target.
lastupdated string, date-time The date the resource was last updated.
name string Name of the target.
version string Version of the underlying schema resource.
versionid string, UUID The version of the resource.

Example Success Response

{
  "address": "arn:aws:iam::252156542978:role/ThingSpace",
  "addressscheme": "streamawsiot",
  "createdon": "2018-12-21T04:37:42.651Z",
  "externalid": "lJZnih8BfqsosZrEEkfPuR3aGOk2i-HIr6tXN275ioJF6bezIrQB9EbzpTRep8J7RmV7QH==",
  "id": "0e411230-c3eb-64dc-f5f4-1020364aa81f",
  "kind": "ts.target",
  "lastupdated": "2018-12-21T04:37:42.651Z",
  "name": "AWS Target",
  "region": "us-east-1",
  "version": "1.0",
  "versionid": "27aca5a4-04da-11e9-bff3-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.