Latest revision as of 07:39, 1 May 2015

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:

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

JSON Mode Response Properties

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

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

JSON Mode Response Properties

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 Property	Child Property	Type	Description
	acctid	Integer	Account ID
	session	Integer	Session ID
	request_type	String	"create"
	contactgroup	Array of Objects	The contactgroup object.
contactgroup	name	String	The name of this group.

Add user or contact

Parent Property	Child Property	Type	Description
	acctid	Integer	Account ID
	session	Integer	Session ID
	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 Property	Child Property	Status	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