> ## Documentation Index
> Fetch the complete documentation index at: https://learn.servitly.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create new thing
> Creates a new thing, i.e. the connected product managed by the DPS.
The thing must be associated either with a thingDefinitionId, or with a productModelId (optionally together with a productModelPartId): this association defines the metrics, alerts, configuration parameters, commands and dashboards available on the thing.
When the locationId is not provided the thing is registered as NOT ASSIGNED, which is allowed to organization users only.
Required permissions: READ_THING, WRITE_THING.
## OpenAPI
````json POST /inventory/things
{
"openapi": "3.1.0",
"info": {
"title": "Servitly DPS API",
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.servitly-sandbox.com",
"description": "[AWS SANDBOX]"
},
{
"url": "https://api.servitly.com",
"description": "[AWS PRODUCTION Ireland]"
},
{
"url": "https://api-ap.servitly.com",
"description": "[AWS Hong Kong]"
},
{
"url": "https://azapi.servitly-dev.com",
"description": "[AZURE DEV Frankfurt]"
},
{
"url": "https://azapi.servitly-staging.com",
"description": "[AZURE STAGING Frankfurt]"
},
{
"url": "https://azapi.servitly.com",
"description": "[AZURE PRODUCTION Frankfurt]"
}
],
"security": [
{
"bearerAuth": []
}
],
"tags": [
{
"name": "ACTIONS"
},
{
"name": "ALERTS"
},
{
"name": "API GATEWAY"
},
{
"name": "AUTHENTICATION"
},
{
"name": "AUTHORIZATIONS"
},
{
"name": "CUSTOMERS"
},
{
"name": "DATA IMPORT / EXPORT"
},
{
"name": "EVENTS"
},
{
"name": "LOCATIONS"
},
{
"name": "MAINTENANCE"
},
{
"name": "MAPPING"
},
{
"name": "METRIC DATA"
},
{
"name": "MOBILE APP"
},
{
"name": "ORGANIZATION"
},
{
"name": "PARTNERS"
},
{
"name": "PRODUCT MODELS"
},
{
"name": "SPARE PARTS"
},
{
"name": "STATISTICS"
},
{
"name": "STORE ORDERS"
},
{
"name": "SUBSCRIPTIONS"
},
{
"name": "SUBSCRIPTIONS (OLD)"
},
{
"name": "THING CONTROL"
},
{
"name": "THING DEFINITIONS"
},
{
"name": "THING MANAGEMENT"
},
{
"name": "THINGS"
},
{
"name": "TICKETS"
},
{
"name": "USER TYPES"
},
{
"name": "USERS"
},
{
"name": "WORK SESSIONS"
}
],
"paths": {
"/inventory/things": {
"post": {
"summary": "Create new thing",
"description": "Creates a new thing, i.e. the connected product managed by the DPS.
The thing must be associated either with a thingDefinitionId, or with a productModelId (optionally together with a productModelPartId): this association defines the metrics, alerts, configuration parameters, commands and dashboards available on the thing.
When the locationId is not provided the thing is registered as NOT ASSIGNED, which is allowed to organization users only.
Required permissions: READ_THING, WRITE_THING.",
"tags": [
"THINGS"
],
"parameters": [
{
"$ref": "#/components/parameters/tenantNameHeader"
}
],
"requestBody": {
"description": "The details of the thing being created.",
"required": "true",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Thing"
}
}
}
},
"responses": {
"201": {
"description": "Successfully created.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Thing"
}
}
}
},
"400": {
"$ref": "#/components/responses/BadRequest"
},
"401": {
"$ref": "#/components/responses/NotAuthenticated"
},
"403": {
"$ref": "#/components/responses/NotAuthorized"
},
"429": {
"$ref": "#/components/responses/ApiLimit"
},
"500": {
"$ref": "#/components/responses/IntError"
}
}
}
}
},
"components": {
"parameters": {
"tenantNameHeader": {
"in": "header",
"name": "X-Servitly-Tenant",
"required": "true",
"schema": {
"type": "string",
"example": "{{tenantName}}"
},
"description": "The name of the tenant (e.g. acme)."
}
},
"schemas": {
"Thing": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The thing object identifier.",
"readOnly": "true"
},
"name": {
"type": "string",
"description": "The thing name."
},
"serialNumber": {
"type": "string",
"description": "The thing serial number."
},
"thingDefinitionId": {
"type": "string",
"description": "The thing-definition identifier associated with the thing."
},
"parentThingId": {
"type": "string",
"description": "The object identifier of the parent thing in the hierarchy."
},
"rootThingId": {
"type": "string",
"description": "The object identifier of the root thing in the hierarchy."
},
"productModelId": {
"type": "string",
"description": "The product-model identifier associated with the thing. This must be provided as an alternative to the thingDefinitionId."
},
"productModelPartId": {
"type": "string",
"description": "The model-part identifier associated with the thing to be provided with the productModelId."
},
"timezone": {
"type": "string",
"description": "The timezone used for date/times localization (e.g. Europe/Rome)."
},
"gpsPosition": {
"type": "string",
"description": "The GPS coordinates associated with this thing."
},
"creationTimestamp": {
"type": "integer",
"format": "int64",
"description": "The timestamp at which the object was created.",
"readOnly": "true"
},
"activationDate": {
"type": "integer",
"format": "int64",
"description": "The last activation date.",
"readOnly": "true"
},
"lastModifiedTimestamp": {
"type": "integer",
"format": "int64",
"description": "The timestamp at which the object was last modified.",
"readOnly": "true"
},
"cloudStatus": {
"type": "integer",
"description": "The cloud status of the thing.
0: INACTIVE
1: TEST
2: ACTIVE
3: SUSPENDED
4: PROVISIONING
5: ACTIVATING
6: ACTIVATING_TEST",
"readOnly": "true"
},
"cloudStatusLastUpdateTimestamp": {
"type": "integer",
"format": "int64",
"description": "The timestamp of the last cloud status update.",
"readOnly": "true"
},
"connectionStatus": {
"type": "integer",
"description": "The connection status of the thing.
-1: UNREACHABLE
0: OFFLINE
1: ONLINE",
"readOnly": "true"
},
"connectionStatusLastUpdateTimestamp": {
"type": "integer",
"format": "int64",
"description": "The timestamp of the last connection status update.",
"readOnly": "true"
},
"latestMetricValueTimestamp": {
"type": "integer",
"format": "int64",
"description": "The timestamp of the latest received metric value.",
"readOnly": "true"
},
"customerId": {
"description": "The customer identifier.",
"type": "string",
"readOnly": "true"
},
"locationId": {
"description": "The location identifier. If missing, the thing is registered as NOT ASSIGNED during creation (allowed only by organization users).",
"type": "string"
},
"properties": {
"$ref": "#/components/schemas/Properties"
},
"simIccid": {
"type": "string",
"description": "The ICCID of the SIM card installed into the product."
},
"simDetails": {
"$ref": "#/components/schemas/SimDetails",
"readOnly": "true"
},
"tagIds": {
"description": "The tag identifiers associated with this thing.",
"type": "array",
"items": {
"type": "string"
}
},
"thingDefinition": {
"description": "The thing-definition associated with the thing.",
"readOnly": "true",
"allOf": [
{
"$ref": "#/components/schemas/ThingDefinition"
}
]
},
"customer": {
"description": "The customer associated with the thing.",
"readOnly": "true",
"allOf": [
{
"$ref": "#/components/schemas/Customer"
}
]
},
"location": {
"description": "The location associated with the thing.",
"readOnly": "true",
"allOf": [
{
"$ref": "#/components/schemas/Location"
}
]
},
"serviceLevel": {
"description": "The service-level associated with the thing.",
"readOnly": "true",
"allOf": [
{
"$ref": "#/components/schemas/ServiceLevel"
}
]
},
"partner": {
"description": "The partner associated with the thing or inherited from the parent location or customer.",
"readOnly": "true",
"allOf": [
{
"$ref": "#/components/schemas/Partner"
}
]
}
}
},
"Properties": {
"type": "object",
"description": "The set of properties providing additional details to the parent object.",
"additionalProperties": {
"type": "string"
},
"example": {
"foo": "abc",
"bar": "123"
}
},
"SimDetails": {
"type": "object",
"description": "The sub-node providing SIM card connectivity and status details.",
"properties": {
"simStatus": {
"type": "string",
"enum": [
"INACTIVE",
"TEST",
"ACTIVE"
],
"description": "The status of the SIM."
},
"sessionStatus": {
"type": "string",
"enum": [
"G",
"A",
"R"
],
"description": "The status of the SIM session."
},
"sessionStartTimestamp": {
"type": "integer",
"format": "int64",
"description": "The timestamp the last session has started."
},
"sessionDataLastTimestamp": {
"type": "integer",
"format": "int64",
"description": "The timestamp the last data has been exchanged by the active session."
},
"sessionNetworkTraffic": {
"type": "integer",
"description": "The number of bytes exchanged during the session."
},
"dailyTraffic": {
"type": "integer",
"description": "The daily average of exchanged bytes."
},
"monthlyTraffic": {
"type": "integer",
"description": "The monthly projection of bytes that will be exchanged."
},
"lastCellId": {
"type": "string",
"description": "The last cell id the SIM has been connected to."
},
"lastUpdate": {
"type": "integer",
"format": "int64",
"description": "The timestamp when the SIM details were last updated."
}
}
},
"ThingDefinition": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The thing definition object identifier.",
"readOnly": "true"
},
"name": {
"type": "string",
"description": "The thing definition name."
},
"description": {
"type": "string",
"description": "The thing definition description."
},
"defaultThingName": {
"type": "string",
"description": "The placeholder-based value used for thing naming."
},
"nameMetricId": {
"type": "string",
"description": "The identifier of the metric providing the Thing name."
},
"serialNumberMetricId": {
"type": "string",
"description": "The identifier of the metric providing the Thing serial number."
},
"gpsPositionMetricId": {
"type": "string",
"description": "The identifier of the metric providing the Thing GPS position in the form \"latitude,longitude\"."
},
"thingDefinitionMetricId": {
"type": "string",
"description": "The identifier of the metric providing the name of the thing-definition used to dynamically change the thing-definition associated with a thing."
},
"superThingDefinitionId": {
"type": "string",
"description": "The identifier of the super thing-definition from which this thing-definition inherits elements (can be set only during creation)."
},
"parentThingDefinitionId": {
"type": "string",
"description": "The identifier of the parent thing-definition this thing-definition is part of."
},
"properties": {
"$ref": "#/components/schemas/Properties"
}
}
},
"Customer": {
"type": "object",
"description": "The bean providing customer details.",
"properties": {
"id": {
"type": "string",
"description": "The customer object identifier.",
"readOnly": "true"
},
"code": {
"type": "string",
"description": "Public, human-readable identifier for the customer. Unlike \"id\", which is the immutable internal identifier, \"code\" is exposed externally and can be modified by clients. Must be unique."
},
"name": {
"type": "string",
"description": "The name of the customer which could be a personal name or a business name."
},
"country": {
"type": "string",
"description": "The country of the customer."
},
"countryIsoCode": {
"type": "string",
"description": "The country ISO Code of the customer."
},
"timezone": {
"type": "string",
"description": "The timezone used for date/times localization (e.g. Europe/Rome)."
},
"properties": {
"$ref": "#/components/schemas/Properties"
},
"creationTimestamp": {
"type": "integer",
"format": "int64",
"description": "The timestamp at which the object was created."
},
"firstAccessTimestamp": {
"type": "integer",
"format": "int64",
"description": "The timestamp at which a client's user first logged in."
},
"lastAccessTimestamp": {
"type": "integer",
"format": "int64",
"description": "The timestamp at which a client's user last logged in."
}
}
},
"Location": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The location object identifier.",
"readOnly": "true"
},
"name": {
"type": "string",
"description": "The location name."
},
"country": {
"type": "string",
"description": "The country of the location."
},
"countryIsoCode": {
"type": "string",
"description": "The country ISO Code of the location."
},
"timezone": {
"type": "string",
"description": "The timezone used for date/times localization (e.g. Europe/Rome)."
},
"gpsPosition": {
"type": "string",
"description": "The GPS coordinates associated with this location."
},
"properties": {
"$ref": "#/components/schemas/Properties"
},
"customerId": {
"type": "string",
"description": "The customer identifier."
},
"customer": {
"description": "The customer identifier (required only for creation).",
"writeOnly": "true",
"allOf": [
{
"$ref": "#/components/schemas/IdRef"
}
]
}
}
},
"ServiceLevel": {
"type": "object",
"properties": {
"id": {
"type": "string",
"readOnly": "true",
"description": "The service-level object identifier."
},
"name": {
"type": "string",
"description": "The name of the service level."
},
"level": {
"type": "integer",
"description": "The integer value used to compare and sort service levels."
},
"alertingFeature": {
"type": "boolean",
"description": "The flag indicating whether the alerts management is enabled or not."
},
"notificationsFeature": {
"type": "boolean",
"description": "The flag indicating whether the notifications management is enabled or not."
},
"thingPricing": {
"type": "object",
"description": "The thing pricing model."
},
"authorizationPricing": {
"type": "object",
"description": "The authorization pricing model."
},
"features": {
"type": "object",
"description": "The list of features enabled on this service level."
}
}
},
"Partner": {
"type": "object",
"properties": {
"id": {
"type": "string",
"readOnly": "true",
"description": "The partner object identifier."
},
"name": {
"type": "string"
},
"code": {
"type": "string",
"description": "Public, human-readable identifier for the partner. Unlike \"id\", which is the immutable internal identifier, \"code\" is exposed externally and can be modified by clients. Must be unique."
},
"country": {
"type": "string",
"description": "The country of the partner."
},
"countryIsoCode": {
"type": "string",
"description": "The country ISO Code of the partner."
},
"timezone": {
"type": "string",
"description": "The timezone used for date/times localization (e.g. Europe/Rome)."
},
"customerCount": {
"type": "number",
"description": "The number of customers associated with the partner."
},
"properties": {
"$ref": "#/components/schemas/Properties"
},
"organization": {
"description": "The parent organization identifier.",
"allOf": [
{
"$ref": "#/components/schemas/IdRef"
}
]
},
"creationTimestamp": {
"type": "integer",
"format": "int64",
"description": "The timestamp at which the object was created."
}
}
},
"IdRef": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "The referenced object identifier.",
"example": "1234abcd"
}
}
}
},
"responses": {
"BadRequest": {
"description": "Request data not valid.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "The error response.",
"example": "Bad request"
}
}
}
}
}
},
"NotAuthenticated": {
"description": "User not authenticated.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "The error response.",
"example": "User not authenticated"
}
}
}
}
}
},
"NotAuthorized": {
"description": "User not authorized.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "The error response.",
"example": "User not authorized"
}
}
}
}
}
},
"ApiLimit": {
"description": "API call rate limit exceeded.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "The error response.",
"example": "API call rate limit exceeded"
}
}
}
}
}
},
"IntError": {
"description": "Internal server error.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "The error response.",
"example": "Internal Server Error"
}
}
}
}
}
}
},
"securitySchemes": {
"bearerAuth": {
"type": "http",
"scheme": "bearer"
}
}
}
}
````