Sensaphone.net API/contactgroup

From Sensaphone.net
Revision as of 11:44, 10 July 2025 by Mwood (Talk | contribs) (→‎Sensaphone.net API: Update Session data type.)

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

Sensaphone.net API

The contactgroup object contains groupings of contacts and users (and thus the contacts that they contain).

Specifications

contactgroups are both top level resources (accessed directly) and are contained as part of the alarm delivery targets contained in alarm schedules. All groups can be manipulated directly by their ID, regardless of whether or not they are contained in other resources.

For example, say a contactgroup is part of an alarm schedule. If you "delete" the contactgroup as part of the alarm schedule (https://rest.sensaphone.net/api/v1/alarmschedule/.../contactgroup/), this would only remove it from the schedule. If you "delete" the contactgroup directly, it will remove all instances of it from every resource it is used in.

The contact group resource has the following properties:

Parent Property Property Type Description Create Delete Read Update
<parent> contactgroup Object The contactgroup object. ✓ ✓ ✓ n/a
contactgroup group_id Integer ID of the contact group. ✓
contactgroup name String The name of this group. ✓ ✓
contactgroup contacts Array of Objects The list of contacts in this group. ✓ ✓
contacts contact_id Integer The contact_id of a contact that is a member of this group. ✓ ✓
contactgroup users Array of Objects The list of groups in this group. ✓ ✓
users user_id Integer The user_id of a user that is a member of this group. ✓ ✓

GET

URI Mode Response URI's:

  • Receive all Contact Group information 
  GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup
  • Receive all Contact IDs in a given Contact Group 
  GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup/{GROUP_ID}/contacts/

JSON Mode Response URI: 

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

JSON Mode Request Properties

Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session String Session Token
  request_type String "read"
  contactgroup Array of Objects The contactgroup object.

JSON Mode Response Properties

Parent PropertyChild PropertyStatus Type Description
  contactgroup Required Array of Objects The parent device object.
contactgroup group_id Optional Integer ID of Device
contactgroup name Optional String The name of this group.
contactgroup contacts Optional Array of Objects The list of contacts in this group.
contacts contact_id Optional Integer The contact_id of a contact that is a member of this group.
contactgroup users Optional Array of Objects The list of users in this group.
users user_id Optional Integer The user_id of a user that is a member of this group.

Example JSON

Receive all Contact Group information

  • Request JSON:
 {
  "acctid": 987654,
  "session": "0123-4567-8901",
  "request_type": "read",
  "contactgroup": null
 }
  • Response JSON:
{
  "result":
  {
    "success": true,
    "code: 0,
    "message": "OK",
  }
  "response":
  {
    "contactgroup":[
     {
       "group_id": 6575,
       "name": "Night Crew",
       "users":
       [ 
         { "user_id": 1234 },
         { "user_id": 1235 }
       ],
       "contacts":
       [
         { "contact_id": 8575 },
         { "contact_id": 8404 }
       ]
     },
     {
       "group_id": 6596,
       "name": "Day Crew",
       "users":
       [ 
         { "user_id": 1433 },
         { "user_id": 1531 }
       ],
       "contacts":
       [
         { "contact_id": 7523 },
         { "contact_id": 6811 }
       ]
     }
    ]
  }
}

PUT

The PUT request for the contact group resource is used to edit the group:

  • Change the name

URI Mode Response URI:

  • Edit a the group name 
 PUT https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup/{GROUP_ID}/name/{GROUP_NAME}

JSON Mode Response URI: 

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

JSON Mode Request Properties

Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session String Session Token
  request_type String "update"
  contactgroup Array of Objects The contactgroup object.
contactgroup group_id Integer ID of Device
contactgroup CHILD PROPERTY   Child properties to be edited *

* One or more contactgroup child properties listed below are required in addition to "group_id".

JSON Mode Response Properties

Parent PropertyChild PropertyStatus Type Description
  contactgroup Required Array of Objects The parent device object.
contactgroup group_id Optional Integer ID of Device
contactgroup name Optional String The name of this group.
contactgroup contacts Optional Array of Objects The list of contacts in this group.
contacts contact_id Optional Integer The contact_id of a contact that is a member of this group.
contactgroup users Optional Array of Objects The list of users in this group.
users user_id Optional Integer The user_id of a user that is a member of this group.

POST

The preferred method to create a new Contact Group is to use the JSON Mode Request. If the URI Mode Request is used you will be adding a Contact Group with only the group_name value, all other values will be left empty until separate POST requests are used. With the JSON Mode Request you can create a Contact Group with all values defined in one step.

URI Mode Response URI's:

  • Create a new Contact Group
Note: A group_name is required when creating a new Contact Group.
  POST https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup/name/{GROUP_NAME}
  • Add an existing user to a Contact Group
Note: The user_id used should be the one received in a user resource GET response. 
 POST https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup/{GROUP_ID}/users/user_id/{USER_ID}
  • Add an existing contact to Contact Group
Note: The contact_id used should be the one received in a contact resource GET response. 
  POST https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup/{GROUP_ID}/contacts/contact_id/{CONTACT_ID}

JSON Mode Request URI: 

  POST https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup

JSON Mode Request Properties

Create new contact group
Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session String Session Token
  request_type String "create"
  contactgroup Array of Objects The contactgroup object.
contactgroup name String The name of this group.
Add user or contact
Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session String Session Token
  request_type String "create"
  contactgroup Array of Objects The contactgroup object.
contactgroup group_id Integer ID of Device
contactgroup contacts Array of Objects The list of contacts in this group.
contacts contact_id Integer The contact_id of a contact that is a member of this group.
contactgroup users Array of Objects The list of users in this group.
users user_id Integer The user_id of a user that is a member of this group.

JSON Mode Response Properties

Parent PropertyChild PropertyStatus Type Description
  contactgroup Required Array of Objects The parent device object.
contactgroup group_id Optional Integer ID of Device
contactgroup name Optional String The name of this group.
contactgroup contacts Optional Array of Objects The list of contacts in this group.
contacts contact_id Optional Integer The contact_id of a contact that is a member of this group.
contactgroup users Optional Array of Objects The list of users in this group.
users user_id Optional Integer The user_id of a user that is a member of this group.

DELETE

URI Mode Request URI's:

  • Delete a Contact Group
  DELETE  https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup/{GROUP_ID}
  • Delete a user from a Contact Group
  DELETE https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup/{GROUP_ID}/users/user_id/{USER_ID}
  • Delete a contact from a Contact Group
  DELETE https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contactgroup/{GROUP_ID}/contacts/contact_id/{CONTACT_ID}

JSON Mode Request URI: 

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

JSON Mode Request Properties

Parent PropertyChild PropertyType Description
  acctid Integer Account ID
  session String Session Token
  request_type String "delete"
  devicegroup Array of Objects The devicegroup object.
contactgroup group_id Integer ID of Device
contactgroup contacts Array of Objects The list of contacts in this group.
contacts contact_id Integer The contact_id of a contact that is a member of this group.
contactgroup users Array of Objects The list of users in this group.
users user_id Integer The user_id of a user that is a member of this group.
Retrieved from "https://wiki.sensaphone.net/index.php?title=Sensaphone.net_API/contactgroup&oldid=308"