Invoke a service

What it does

Invokes a one-shot action. There is no persistent state—each call runs once and is not idempotent. A timeout does not mean the action did not run. Use the full serviceId. Actions use this API, not device.property.set.

For PTZ movement, use ptz.aim.relative. Input fields are documented on the PTZ pages.

Request URL

POST https://openapi-[DataCenter].easy4ip.com/openapi/v2/device.service.invoke

Minimum permission

An administrator needs no extra permission on a device they bound. A shared device needs permission for the capability that owns the action (for example, PTZ actions need PTZ permission). A bound sub-user needs none. A sub-account needs the auth code for that capability (for example, Ptz for PTZ).

Request parameters

Name	Type	Required	Allowed values	Description
`token`	String	yes		Administrator, sub-user, or sub-account accessToken
`deviceId`	String	yes		Device serial number
`productId`	String	no		Optional. If sent and it does not match the device model → `DV2009`
`channelId`	String	conditional	Channel index; IPCs often `"0"`. Do not pass `-1`	Required for channel-level actions; omit for device-level
`serviceId`	String	yes	Full `serviceId`, e.g. `ptz.aim.relative`	One service per request
`inputData`	Object	conditional	`field` keys from `inputData` in `device.capability.list` or on the service page	Required when that `inputData` array is non-empty; use `{}` when there are no inputs. Speed fields are often strings, e.g. `"0.5"`, not numbers

Common request fields and signing: Signing and Common request payload.

Request example

{
 "id": "d5c287b4-5b2f-4f03-baf5-8032c5c354af",
 "system": {
 "ver": "1.0",
 "appId": "lcdxxxxxxxxx",
 "sign": "xjhCQBoJ9hRDsCjyDcHjtDNzRZ3ZJezcawsfWeiaoxU=",
 "time": 1706511734,
 "nonce": "f5a1ae2d-c09c-4d39-a744-83a5c2c653c2"
 },
 "params": {
 "token": "<yourAccessToken>",
 "deviceId": "TESTIPC000012345",
 "channelId": "0",
 "serviceId": "ptz.aim.relative",
 "inputData": {
 "horizontal": "0.5",
 "vertical": "0",
 "zoom": "0",
 "duration": 1000
 }
 }
}

Response data fields

Name	Type	Description
`outputData`	Object	Service output. `{}` when there are no outputs. Field names match the catalog entry, e.g. `ptz.cruise.get`

Response example

No outputs (e.g. ptz.aim.relative):

{
 "id": "d5c287b4-5b2f-4f03-baf5-8032c5c354af",
 "result": {
 "code": "0",
 "msg": "Operation is successful",
 "data": {
 "outputData": {}
 }
 }
}

With outputs (ptz.cruise.get, inputData {}):

{
 "id": "d5c287b4-5b2f-4f03-baf5-8032c5c354af",
 "result": {
 "code": "0",
 "msg": "Operation is successful",
 "data": {
 "outputData": {
 "cruiseModel": "1",
 "collection": [
 {
 "name": "Front door",
 "stayTime": "15"
 }
 ],
 "cruises": [
 {
 "beginTime": "08:00:00",
 "endTime": "18:00:00",
 "period": "1111100"
 }
 ]
 }
 }
 }
}

Error codes

This API may return the codes below.

Gateway and device codes: Global return codes.