Sensaphone.net API/user

From Sensaphone.net
Revision as of 07:38, 1 May 2015 by Tim (Talk | contribs) (→‎Example JSON)

(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Sensaphone.net API

Specifications

The user resource allows access to information relating to two classes of persons: those who will have access to the website and API and those who will be notified in the event of an alarms. A user may be in one, both, or neither class.

The user resource has the following properties:

Parent PropertyProperty Type Description Create Delete Read Update
<parent> user Object The user object. ✓ ✓ ✓ n/a
user user_id Integer ID of the user. ✓
user name String Name of user. ✓ ✓
user enable Boolean If the user is enabled. ✓ ✓
user alarm_user_mode String The alarm user mode ✓ ✓
user site_user_level String The site user access level ✓ ✓
user is_site_user Boolean If the user has site access (website or API) ✓
user site_user Object sub-object contains data for where is_site_user is 'true'. Is still accessed using the "user" resource ✓
site_user devices Array of String List of devices (device_guid) accessible by this user. ✓ ✓ ✓
site_user groups Array of Integer group IDs of the groups accessible by this user. ✓ ✓ ✓
site_user username String The username to access the website or API ✓ ✓
site_user access_level String The current access level for website or API access. ✓ ✓
site_user address Object (See Sensaphone.net API/address) ✓ ✓
user is_alarm_user Boolean If the user is enabled for alarm delivery. ✓
user alarm_user Object sub-object contains data for where is_alarm_user is 'true'. Is still accessed using the "user" resource. ✓ ✓
alarm_user schedule Object (See Sensaphone.net API/schedule) ✓ ✓
alarm_user contact Array of Object (See Sensaphone.net API/contact) ✓ ✓

GET

URI Request Mode URI's:

  • Retrieve all user data for all users in the account.
   GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user
  • Retrieve all user data for a specific user. 
    GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}
  • Retrieve the name of a specific user.
    GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/name

JSON Request Mode URI: 

    POST https://rest.sensaphone.net/api/v1/user

JSON Mode Request Properties

Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session Integer Session ID
  request_type String "read"
  <parent object(s)> Array of Objects The parent(s) of the "user" resource, if any. See the list.
<parent> user Array of Objects The user object

JSON Mode Response Properties

Parent PropertyChild PropertyStatus Type Description
  <parent object(s)> Optional Array of Objects The parent(s) specified in the request.
<parent> user Required Array of Objects The user object
user user_id Optional Integer ID of user
user name Optional String Name of user
user enable Optional Boolean If the user is enabled.
user alarm_user_mode Optional String The alarm user mode.
user site_user_level Optional String The site user access level
user is_site_user Optional Boolean If the user has site access (website or API)
user site_user Optional Object sub-object contains data for where is_site_user is 'true'. Is still accessed using the "user" resource.
site_user devices Optional Array of String List of devices (device_guid) accessible by this user.
site_user groups Optional Array of Integer group IDs of the groups accessible by this user.
site_user username Optional String The username to access the website or API
site_user access_level Optional String The current access level for website or API access.
site_user address Optional Object (See Sensaphone.net API/address)
user is_alarm_user Optional Boolean If the user is enabled for alarm delivery.
user alarm_user Optional Object sub-object contains data for where is_alarm_user is 'true'. Is still accessed using the "user" resource.
alarm_user schedule Optional Object (See Sensaphone.net API/schedule)
alarm_user contact Optional Array of Objects (See Sensaphone.net API/contact)

Example JSON

Receive all User information

  • Request JSON:
{
  "request_type":"read",
  "resource":"user",
  "acctid":987654,
  "session":"0123-4567-8901",
  "user": null                 ← On a "read", a null property can be used to retrieve all instances of that property.
}
  • Response JSON:
{
  "result":
  {
    "success":true.
    "code":0,
    "message":"OK",
  },
  "response":
  {
    "user":[
     {
      "user_id": 1010
      "name": "John Doe",
      "enable": true,
      "is_site_user": true,
      "site_user": {
        "devices": [
          "00-11-22-33-44-55",
          "AA-BB-CC-DD-EE-FF"
        ],
        "groups": [
          12345,
          85693
        ],
        "username": "[email protected]",
        "access_level": "Admin",
        "address":{
          ...                       ← See here for address object specification       
        }
      },
      "is_alarm_user": true,
      "alarm_user": {
        "schedule":{
          ...                       ← See here for schedule object specification
        },
        "contact":[
          {
            "contact_id": 1201,
            ...                     ← See here for contact object specification
          },
          {
            "contact_id": 1202,
            ...
          },
          {
            "contact_id": 1203,
            ...
          }
        ]
      }
     },
     {
      "user_id": 1023
      ...                           ← More than one user is returned because a "null" user was requested.
     }
    ]
  }
}

PUT

URI Mode Request URI's:

  • Edit a user's name value 
   PUT https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/name/{NAME}

JSON Mode Request URI: 

   POST https://rest.sensaphone.net/api/v1/user

JSON Mode Request Properties

Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session Integer Session ID
  request_type String "update"
  <parent object(s)> Array of Objects The parent(s) of the "user" resource, if any. See the list.
<parent> user Array of Objects The user object
user user_id Integer ID for user
user CHILD PROPERTY   User's child properties to be edited*

*One or more user child properties listed below are required in addition to "user_id".

JSON Mode Response Properties

Parent PropertyChild PropertyStatus Type Description
  <parent object(s)> Optional Array of Objects The parent(s) specified in the request.
<parent> user Required Array of Objects The user object
user user_id Optional Integer ID of user
user name Optional String Name of user
user enable Optional Boolean If the user is enabled.
user alarm_user_mode Optional String The alarm user mode.
user site_user_level Optional String The site user access level
user is_site_user Optional Boolean If the user has site access (website or API)
user site_user Optional Object sub-object contains data for where is_site_user is 'true'. Is still accessed using the "user" resource.
site_user devices Optional Array of String List of devices (device_guid) accessible by this user.
site_user groups Optional Array of Integer group IDs of the groups accessible by this user.
site_user username Optional String The username to access the website or API
site_user password Optional String The password to access the website or API
site_user access_level Optional String The current access level for website or API access.
site_user address Optional Object (See Sensaphone.net API/address)
user is_alarm_user Optional Boolean If the user is enabled for alarm delivery.
user alarm_user Optional Object sub-object contains data for where is_alarm_user is 'true'. Is still accessed using the "user" resource.
alarm_user schedule Optional Object (See Sensaphone.net API/schedule)
alarm_user contact Optional Array of Objects (See Sensaphone.net API/contact)

POST

The preferred method to create a new User is to use the JSON Mode Request. If the URI Mode Request is used you will be adding a User with only the name value, all other values will be left empty until a PUT request is used. With the JSON Mode Request you can create a User with all values defined in one step.

URI Mode Request URI:

  • Create a new User 
  POST https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/name/{NAME}

JSON Mode Request URI 

  POST https://rest.sensaphone.net/api/v1/user

JSON Mode Request Properties

Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session Integer Session ID
  request_type String "create"
  <parent object(s)> Array of Objects The parent(s) of the "user" resource, if any. See the list.
<parent> user Array of Objects The user object
user name String Name of user
user CHILD PROPERTY   Additional child properties to be set*

*One or more user child properties listed below may be specified in addition to "user_id" and "name".

JSON Mode Response Properties

Parent PropertyChild PropertyStatus Type Description
  <parent object(s)> Optional Array of Objects The parent(s) specified in the request.
<parent> user Required Array of Objects The user object
user user_id Optional Integer ID of user
user name Optional String Name of user
user enable Optional Boolean If the user is enabled.
user alarm_user_mode Optional String The alarm user mode.
user is_site_user Optional Boolean If the user has site access (website or API)
user site_user Optional Object sub-object contains data for where is_site_user is 'true'. Is still accessed using the "user" resource.
site_user devices Optional Array of String List of devices (device_guid) accessible by this user.
site_user groups Optional Array of Integer group IDs of the groups accessible by this user.
site_user username Optional String The username to access the website or API
site_user password Optional String The password to access the website or API
site_user access_level Optional String The current access level for website or API access.
site_user address Optional Object (See Sensaphone.net API/address)
user is_alarm_user Optional Boolean If the user is enabled for alarm delivery.
user alarm_user Optional Object sub-object contains data for where is_alarm_user is 'true'. Is still accessed using the "user" resource.
alarm_user schedule Optional Object (See Sensaphone.net API/schedule)
alarm_user contact Optional Array of Objects (See Sensaphone.net API/contact)

DELETE

URI Mode Request URI's:

  • Delete a User
  DELETE https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}

JSON Mode Request URI: 

  POST https://rest.sensaphone.net/api/v1/user

JSON Mode Request Properties

Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session Integer Session ID
  request_type String "delete"
  <parent object(s)> Array of Objects The parent(s) of the "user" resource, if any. See the list.
<parent> user Array of Objects The user object
user user_id Integer ID for user
Retrieved from "https://wiki.sensaphone.net/index.php?title=Sensaphone.net_API/user&oldid=70"