Create New Pin on a Zone Map API

Require Authentication

This API is used to create new pin on a zone map for the company based on combination of deviceID and token.

Pin/bin/assets creation has a limit number of pin/bin/assets that can be created, depends on user account type.

URL

api/projects/addpin/:projectID

Required parameter (in URL)

:projectID «contains zone ID. Value must exist in database. It must be put in the URL, e.g: api/projects/addpin/1. To get available projectID, please visit Get Available Zones»

Required parameter (POST)

deviceID
token
latitude
longitude
pintypeID «contains asset type ID. Value must exist in database. To get available asset type ID, please visit Get Available Asset Types»
iconType «contains icon type. Accepted value: "system", "custom", "pintype".»
iconID «contains iconID based in iconType. If iconType is "pintype", iconID can be ignored (not passed). "pintype" indicates that it will use default icon based on its asset type (pintypeID). If iconType is "system", iconID value must exist in System-default Icons. If iconType is "custom", iconID value must exist in Custom Icons.»

Required or Optional parameter (POST)

Optional parameter (POST)

name «contains pin name» if asset type (pintypeID) have pattern that will be used as default pin name (field pinTypeRuleForPinName is empty), and the pattern result is not empty string. If empty, it will use asset Type name as its name. If this optional field "name" is passed, it will overrides the pattern result.
description
serialNumber
assetTag «in array format [{"type":"existing","value":1},{"type":"new","value":"text"}]. If passed, it will delete all tags assigned to this pins before insert new ones. To delete, pass empty array []. If the type is "new", value must be a string to be stored as tags_text. If the type is "existing", value must be pinstagsID found in Get Available Tags»
projectgroupID «contains group ID. If passed, value must exist in database, based on projectID. If value is not exist, system will skip this field (leave it blank). To get available group ID, please visit Get Available Groups»
manufacturerID «contains manufacturerID. If this parameter is not passed, it will be filled with asset type manufacturerID based on pintypeID in required parameter. If passed, value must be exist in database. To get the manufacturerID, please see Get Available Manufacturers»
pinAddress1
pinAddress2
pinCity
pinState
pinCountry
pinZipCode
customlocationID «contains customlocationID. If passed, value must be exist in database, or it can have "0" value to skip auto-assigned custom location. If this parameter is passed and pin full address is empty, pin full address will be filled with custom location full address (if any). To get the customlocationID, please see Get Available Custom Locations»
sensorsID «contains sensorsID to be allocated. Only available for non-demo account. If passed, value must be exist in database, sensorsID must not be available (not allocated), and parameter depthWhenEmpty_cm and distanceSensorToFillLine_cm must be passed and not empty. If this parameter is passed and pin full address is empty, pin full address will be filled with custom location full address (if any). To get the customlocationID, please see Get Available Sensors»
depthWhenEmpty_cm «contains integer value of height of container from bottom to fill line in centimeters (cm). Minimum value is 1. Only available for non-demo account. This parameter must be passed if sensorsID is passed.»
distanceSensorToFillLine_cm «contains integer value of distance of sensor from top of fill line in centimeters (cm). Only available for non-demo account. This parameter must be passed if sensorsID is passed.»
vendorID «contains vendorID based in vendor, vendorID value must exist in Vendor.»

Note:
If customlocationID is not passed, but pin latitude and longitude are inside radius of certain custom location, system will automatically fill customlocationID with the nearest custom location.
If pin address is empty, and not using customlocationID, pin address will be automatically filled bu related data from Google API based on latitude and longitude in required parameter. If using customlocationID, address will be filled by custom location address. Related data from Google Maps API is as below:

pinAddress1 = route + street_number
pinAddress2
pinCity = administrative_area_level_2
pinState = administrative_area_level_1
pinCountry = country
pinZipCode = postal_code

Example JSON Payload

{
	"deviceID": "ABCD-EFGH-IJKL-MNOP",
	"token": "bb602ab13b8090268cd6e3bb9dfa39e2",
	"latitude": -6.202423572540,
	"longitude": 106.779052734375,
	"pintypeID": 1,
	"manufacturerID": 1,
	"iconType": "pintype",
	"customlocationID": 1,
	"sensorsID": 1,
	"depthWhenEmpty_cm": 100,
	"distanceSensorToFillLine_cm": 10,
	"assetTag": [{
		"type": "existing",
		"value": 1
	}, {
		"type": "new",
		"value": "tags api"
	}]
}

{
	"deviceID": "ABCD-EFGH-IJKL-MNOP",
	"token": "bb602ab13b8090268cd6e3bb9dfa39e2",
	"latitude": -6.202423572540,
	"longitude": 106.779052734375,
	"pintypeID": 1,
	"name": "test pin zone API",
	"iconType": "system",
	"iconID": 1
}

Possible return HTTP status code

Return message, contains newly created pin project

{
	"status": "success",
	"message": {
		"projectpinID": 13856,
		"projectID": 677,
		"projectName": "Sample API",
		"projectgroupID": 0,
		"groupName": "",
		"iconType": "system",
		"iconID": 1,
		"iconURL": "",
		"iconName": "",
		"customlocationID": 0,
		"locationName": "",
		"pinAddress1": "",
		"pinAddress2": "",
		"pinCity": "",
		"pinState": "",
		"pinCountry": "",
		"pinZipCode": "",
		"latitude": -6.20242357254,
		"longitude": 106.77905273438,
		"name": "test pin zone API",
		"description": "",
		"serialNumber": "",
		"manufacturerID": 0,
		"manufacturerName": "",
		"createdDate": 1692268877,
		"creatorUserID": 90,
		"pinType": {
			"pintypeID": 134,
			"pinTypeName": "bb test",
			"depthWhenEmpty_cm": 20,
			"distanceSensorToFillLine_cm": 2,
			"iconType": "system",
			"iconID": 2,
			"iconURL": "https://wasteinsights-public-files.s3.ap-southeast-2.amazonaws.com/images/icons/default/appsize/wheelie.png",
			"pinTypeDescription": "",
			"pinTypeImageOriginalName": "",
			"pinTypeImageURL": "",
			"manufacturerID": 0,
			"manufacturerName": "",
			"pinTypeCreatedDate": 1591353799,
			"pinTypeCreatedByUserID": 90,
			"pinTypeModifiedDate": 1614829214,
			"pinTypeModifiedByUserID": 90,
			"total_projectpins": 34,
			"iconName": "Wheelie Bin"
		},
		"currentAllocatedSensor": [],
		"assetTag": []
	}
}

Note:
Since customlocationID is optional, if customlocationID is set to 0 and locationName is set to empty string, it indicates that asset type does not have custom location assigned.
Since manufacturerID is optional, if manufacturerID is set to 0 and manufacturerName is set to empty string, it indicates that asset type does not have manufacturer assigned.

Superfy Platform API Documentation