APIs (V1.6)

The LinkTap APIs are intended for users to integrate the LinkTap products with third-party Home Automation Systems. Currently there are 11 APIs available:
  1. Activate Instant Mode for Watering ON and OFF
  2. Activate Interval Mode
  3. Activate Odd-Even Mode
  4. Activate Seven Day Mode
  5. Activate Month Mode
  6. Activate Calendar Mode
  7. Pause Watering Plan
  8. Clear Alarm
  9. Query watering historical data for the past 30 days
  10. Set or update a webhook url for receiving various events (e.g., watering start, watering end, etc.)
  11. Delete the webhook url
  12. Create a new API key or retrieve existing API key
Please note:
1) The Content-Type in all requests needs to application/json or application/x-www-form-urlencoded.
2) If you use Postman to test APIs, please make sure "raw" and "JSON (application/json)" in Body section are selected.
If you have further requirements, please contact us at support@link-tap.com
Create / Retrieve Your API's Key
   
   

Your API Key is {{apiKey.value}}. Please keep your API key confidential and do not divulge it to anyone.
There is no API Key associated with your LinkTap account.
API Descriptions
1. Activate Instant Mode for Watering ON and OFF
POST https://www.link-tap.com/api/activateInstantMode

Please note: Rate limiting is applied for this API. The minimum interval of calling this API is 15 seconds.

Body object:
username: Required. String type. Your LinkTap account's username
apiKey: Required. String type. Your API key
gatewayId: Required. String type. Your LinkTap Gateway's first 16-digits/letters ID, case insensitive, no dash symbol, e,g, 3F7A23FE004B1200
taplinkerId: Required. String type. Your LinkTap Taplinker's first 16-digits/letters ID, case insensitive, no dash symbol, e,g, 67ABCDEF004B1200. If the device is the ValveLinker or multiple-outlet water timer, this field should be a 18-digits/letters/underscore ID, e.g., 67ABCDEF004B1200_1.
action: Required. String or Boolean type. "true" for Watering ON, "false" for Watering OFF.
duration: Required. Number type. The watering duration (unit is minute). For Watering OFF, this field is 0. For Watring ON, the range is from 1 minute to 1439 minutes for the G1 and G2 models, and from 0 to 1439 minutes for the G1S and G2S models.
durationSec: Optional. Number type. The second portion of the watering duration (unit is second). It is used for the G1S and G2S models only. Its value is between 0 and 59. An example: if you want to water for 10 minutes 30 seconds, then the duration field will be 10, and the durationSec field will be 30.
eco: Optional. String or Boolean type. "true" for ECO enabled, "false" for ECO disabled.
ecoOn: Required when eco equals "true". Number type. The valve ON duration (unit is minute). This value needs to be less than duration.
ecoOnSec: Optional. Number type. The second portion of the valve ON duration (unit is second). It is valid for the G1S, G2S and D1 models only. Its value is between 0 and 59.
ecoOff: Required when eco equals "true". Number type. The valve OFF duration (unit is minute).
ecoOffSec: Optional. Number type. The second portion of the valve OFF duration (unit is second). It is valid for the G1S, G2S and D1 models only. Its value is between 0 and 59.
autoBack: Optional. String or Boolean type. "true" for automatically re-activating the previous watering plan after watering in Instant Mode is completed.
Response (success):
result: "ok"
message: "success"
Response (failure):
result: "error"
message: various error messages
Example of Request Body for Watering ON:
{
username: linktapuser,
apiKey: "a6f1223d1fe191f8ec55662d1eb45720",
gatewayId: "3C7A23FE004B1200",
taplinkerId: "68ABCDEF004B1200",
action: true,
duration: 20
eco: true,
ecoOn: 1
ecoOff: 2
}
Example of Request Body for Watering OFF:
{
username: linktapuser,
apiKey: "a6f1223d1fe191f8ec55662d1eb45720",
gatewayId: "3C7A23FE004B1200",
taplinkerId: "68ABCDEF004B1200",
action: false,
duration: 0
}
Curl example:
curl -d "username=YourUsername&apiKey=YourApiKey&gatewayId=YourGatewayId&taplinkerId=YourTaplinkerId&action=true&duration=20&eco=true&ecoOn=1&ecoOff=2" -X POST https://www.link-tap.com/api/activateInstantMode
Please be noted that when this API is sussessfully processed by the LinkTap server, a pop-up message -- Instant mode (watering off) has been activated -- will be displayed on your mobile app or web app if it is currently being opened. This message does NOT reflect the actual watering status of your taplinker in this scenario. It can be safely ignored. To view the actual watering status of your taplinker, please re-login to the app.
2. Activate Interval Mode
POST https://www.link-tap.com/api/activateIntervalMode

Please note: Rate limiting is applied for this API. The minimum interval of calling this API is 15 seconds.

Since 03/2021, users have been able to create and activate up to 3 interval mode watering plans through the LinkTap app. After this API gets called, all (1 or 2 or 3) interval mode watering plans will be activated.

Body object:
username: Required. String type. Your LinkTap account's username
apiKey: Required. String type. Your API key
gatewayId: Required. String type.
taplinkerId: Required. String type. A 16 (for TapLinker) or 18 (for ValveLinker or multiple-outlet water timer) digits/letters/underscore ID.
Response (success):
result: 'ok'
message: 'success'
Response (failure):
result: 'error'
message: various error messages
3. Activate Odd-Even Mode
POST https://www.link-tap.com/api/activateOddEvenMode

Please note: Rate limiting is applied for this API. The minimum interval of calling this API is 15 seconds.

Body object:
username: Required. String type. Your LinkTap account's username
apiKey: Required. String type. Your API key
gatewayId: Required. String type.
taplinkerId: Required. String type. A 16 (for TapLinker) or 18 (for ValveLinker or multiple-outlet water timer) digits/letters/underscore ID.
Response (success):
result: 'ok'
message: 'success'
Response (failure):
result: 'error'
message: various error messages
4. Activate Seven Day Mode
POST https://www.link-tap.com/api/activateSevenDayMode

Please note: Rate limiting is applied for this API. The minimum interval of calling this API is 15 seconds.

Body object:
username: Required. String type. Your LinkTap account's username
apiKey: Required. String type. Your API key
gatewayId: Required. String type.
taplinkerId: Required. String type. A 16 (for TapLinker) or 18 (for ValveLinker or multiple-outlet water timer) digits/letters/underscore ID.
Response (success):
result: 'ok'
message: 'success'
Response (failure):
result: 'error'
message: various error messages
5. Activate Month Mode
POST https://www.link-tap.com/api/activateMonthMode

Please note: Rate limiting is applied for this API. The minimum interval of calling this API is 15 seconds.

Body object:
username: Required. String type. Your LinkTap account's username
apiKey: Required. String type. Your API key
gatewayId: Required. String type.
taplinkerId: Required. String type. A 16 (for TapLinker) or 18 (for ValveLinker or multiple-outlet water timer) digits/letters/underscore ID.
Response (success):
result: 'ok'
message: 'success'
Response (failure):
result: 'error'
message: various error messages
6. Activate Calendar Mode
POST https://www.link-tap.com/api/activateCalendarMode

Please note: Rate limiting is applied for this API. The minimum interval of calling this API is 15 seconds.

Body object:
username: Required. String type. Your LinkTap account's username
apiKey: Required. String type. Your API key
gatewayId: Required. String type.
taplinkerId: Required. String type. A 16 (for TapLinker) or 18 (for ValveLinker or multiple-outlet water timer) digits/letters/underscore ID.
Response (success):
result: 'ok'
message: 'success'
Response (failure):
result: 'error'
message: various error messages
7. Pause Watering Plan(s)
POST https://www.link-tap.com/api/pauseWateringPlan

Please note: Rate limiting is applied for this API. The minimum interval of calling this API is 15 seconds.

Body object:
username: Required. String type. Your LinkTap account's username
apiKey: Required. String type. Your API key
gatewayId: Required. String type.
taplinkerId: Required when pausing a watering plan for one device/zone. Ignored by the server if pausing watering plans for all devices/zones. String type. A 16 (for TapLinker) or 18 (for ValveLinker or multiple-outlet water timer) digits/letters/underscore ID.
pauseDuration: Required. Number type (unit: hour). Ranged from 0.1 to 240 hours. Use -1 to initiate an indefinite pause.
allDevice: Optional. Boolean type. "true" for pausing all devices/zones under one gateway.
overwrite: Optional. String type. Three valid values: 'never', 'always', and 'ifTemporary'.
'never': Does not allow to start a new pause session when the device is already paused.
'always': Always allow to start a new pause session when the device is already paused.
'ifTemporary': Does not allow to start a new pause session only when the device is already paused indefinitely.
Response (success):
result: 'ok'
message: 'success'
Response (failure):
result: 'error'
message: various error messages
8. Clear Alarm
POST https://www.link-tap.com/api/dismissAlarm

Body object:
username: Required. String type. Your LinkTap account's username
apiKey: Required. String type. Your API key
gatewayId: Required. String type.
taplinkerId: Required. String type. A 16 (for TapLinker) or 18 (for ValveLinker or multiple-outlet water timer) digits/letters/underscore ID.
alarm: Required. String type. Must be one of the followings.
'noWater': Water cut-off or stop flowing alert
'valveBroken': Water shut-off failure alert
'fallFlag': Device fall alert
'pcFlag': Unusually low flow alert
'pbFlag': Unusually high flow alert
Response (success):
result: 'ok'
message: 'success'
Response (failure):
result: 'error'
message: various error messages
9. Query Watering Historical Data for the Past 30 Days
POST https://www.link-tap.com/api/getWateringHistory

Please note: Rate limiting is applied for this API. The minimum interval of calling this API is 10 minutes.

Body object:
username: Required. String type. Your LinkTap account's username
apiKey: Required. String type. Your API key
taplinkerId: Required. String type. Only first 16 (for TapLinker) or 18 (for ValveLinker or multiple-outlet water timer) letters/numbers should be used here.
Response (success):
result: 'ok'
status: null when no watering historical data of the past 30 days is found.

Explanation of relevant fields in the watering historical data:
Y: the date a watering cycle ended. Its format is YYYYMMDD.
H: the hour (0 - 23) a watering cycle ended.
M: the minute (0 - 59) a watering cycle ended.
ss: the second (0 - 59) a watering cycle ended.
D: the minute part of the duration of a watering cycle.
S: the second part (0 - 59) of the duration of a watering cycle.
vol: total volume of a watering cycle. (unit: ml. For G2 and G2S only).
Response (failure):
result: 'error'
message: various error messages
10. Set or update a webhook url for receiving various events and messages
POST https://www.link-tap.com/api/setWebHookUrl

Body object:
username: Required. String type. Your LinkTap account's username
apiKey: Required. String type. Your API key
webHookUrl: Required. String type. The webhook url to receive various events and messages as stated below

Events:
  • 'watering start'
  • 'watering end'
  • 'watering cycle skipped'
  • 'gateway offline' : (note: when the Gateway has been offline for 6 hours)
  • 'gateway online' : (note: if the "gateway offline" event has been dispatched previously)
  • 'device offline' : (note: when the device has been offline for 12 hours)
  • 'battery low alert'
  • 'battery good' : (note: after the 'battery low alert' is issued AND the new full batteries are put in, the 'battery good' event will be issued. The new battery value will be seen in the 'content' field.)
  • 'water cut-off alert'
  • 'unusually high flow alert'
  • 'unusually low flow alert'
  • 'valve broken alert'
  • 'device fall alert'
  • 'manual button pressed' : (note: when the Manual Button Lockout Status is set to 'Partially enabled' or 'Fully enabled')
  • 'freeze alert'
  • 'alarm clear'

When an event occurs, the LinkTap system will send the following JSON object by calling the supplied webhook url. No response is required.
{
username: xxxxx
event: xxxxx
title: xxxxx
content: xxxxx
gatewayId: xxxxxxxxxxxxxxxx
deviceId: xxxxxxxxxxxxxxxx
}
For the 'watering start' event, an extra property 'workMode' is also included in the object. It denotes the currently activated watering mode.
  • 'M': Instant mode
  • 'I': Interval mode
  • 'T': 7-day mode
  • 'O': Odd-even mode
  • 'D': Calendar mode
  • 'Y': Month mode
  • 'N': No mode is activated

Messages:
  • 'wateringOn'
  • 'wateringOff'
  • 'flowMeterValue'
When a watering session takes place, the above 3 messages will be pushed to the webhook. In addition, 'battery' and 'signal' values will be included in the 'wateringOff' and the first 'wateringOn' messages.

  • 'deviceOffline'
  • 'deviceOnline'
Note: If the device's wireless connection with the Gateway is shaky, a large amount of 'deviceOnline' and 'deviceOffline' messages are likely to be pushed to the webhook. Such a scene is certainly not desirable. To improve the wireless communication performance, please refer to our FAQ page.

  • 'gatewayOffline'
  • 'gatewayOnline'
Note: If the Gateway's connection with the cloud server is not stable, a large amount of 'gatewayOffline' and 'gatewayOnline' messages are going to be pushed to the webhook. This kind of issue is unlikely to occur if the Gateway is hardwired to the home router and the home Internet service is stable. If the Gateway is connected to a Wi-Fi extender, please make sure that the Wi-Fi extender has solid communication with the home router/hub.

  • 'flowMeterStatus'
Response (success):
result: 'ok'
message: 'success'
Response (failure):
result: 'error'
message: various error messages
11. Delete the webhook url to stop receiving events
POST https://www.link-tap.com/api/deleteWebHookUrl

Body object:
username: Required. String type. Your LinkTap account's username
apiKey: Required. String type. Your API key
Response (success):
result: 'ok'
message: 'success'
Response (failure):
result: 'error'
message: various error messages
12. Create a new API key or retrieve existing API key
POST https://www.link-tap.com/api/getApiKey

Body object:
username: Required. String type. Your LinkTap account's username
password: Required. String type. Your LinkTap account's password
replace: Optional. String or Boolean type. If the value is true, the call will generate a new API Key. Otherwise the call will return the existing API Key. The default value is false.
Response (success):
result: 'ok'
message: New or existing API Key
Response (failure):
result: 'error'
message: various error messages