Sensaphone.net API/contact

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

Jump to: navigation, search

Sensaphone.net API

The Destination object contains the information needed for alarm notifications to a User, Call Lists, and/or Alarm Schedule.

Specifications

  • A contact is its own API resource. It represents a single destination for alarm delivery. The resource will be used for creating, adding, and editing both user dependent and independent contacts in Call List or Alarm Schedule. In addition, a contact object can be accessed from other API resources such as User and Contact Group.

The contact resource has the following properties:

Parent PropertyProperty Type Description Create Delete Read Update
<parent> contact Object The contact object. ✓ ✓ ✓ n/a
contact contact_id Integer ID of the contact. ✓
contact destination String The destination. ✓ ✓
contact type String The destination's type. ✓ ✓
contact description String The destination's description. ✓ ✓
contact enable Boolean If the contact is enabled. ✓ ✓
contact schedule Object (See Sensaphone.net API/schedule) ✓ ✓

GET

URI Mode Request URI's:

  • Retrieve all information for all of a user's contacts.
  GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/alarm_user/contact
  • Retrieve the description of a specific user's contact.
  GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/alarm_user/contact/{CONTACT_ID}/description
  • Retrieve all of the contact IDs for a particular user's contacts.
  GET https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/alarm_user/contact/contact_id

JSON Mode Request URI: 

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

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 "contact" resource, if any. See the list.
<parent> contact Array of Objects The contact 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> contact Required Array of Objects The contact object
contact contact_id Optional Integer ID for contact
contact type Optional String Phone, SMS or Email (Use a V2 read command to retrieve the valid values)
contact destination Optional String Phone number, Email address, etc. of contact's destination
contact description Optional String Short description describing the destination ex: "Work Phone"
contact schedule Optional Object (See Sensaphone.net API/schedule)
contact enable Optional Boolean If the contact is enabled.

Example JSON

Retrieve all the contact information for a particular user.

  • Request JSON
  {
     "acctid":987654,
     "session":"0123-4567-8901",
     "request_type":"read",
     "user": [                  ← "user" is a parent object
       "user_id":395,
       "contact": 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":[
      {
        "alarm_user": {
          "user_id":395,
          "contact":[
            {
              "contact_id":0001,
              "type":"Phone",
              "destination":"555 555 5555",
              "description": "Work Phone",
              "enable": true,
              "schedule":{
                "schedule_id": 345567,
                ...                         ← See here for schedule object specification
              }
            },
            {
              "contact_id":0002,
              "type":"SMS",
              "destination":"555 555 5555",
              "description": "Cell Phone"
              "enable": true,
              "schedule":{
                "schedule_id": 412571,
                ...
              }
            },
            {
              "contact_id":0003,
              "type":"Email",
              "destination":"[email protected]",
              "description": "Work Email"
              "enable": true,
              "schedule":{
                "schedule_id": 567437,
                ...
              }
            }
          ]
         }
       }
    ]
  }
}

PUT

URI Mode Request URI's

  • Edit the description of a contact
  PUT https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/contact/{CONTACT_ID}/description/{DESCRIPTION}
  • Edit the destination of a contact
  PUT https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/contact/{CONTACT_ID}/destination/{DESTINATION}
  • Edit the contact's destination type
  PUT https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/contact/{CONTACT_ID}/type/{TYPE}

JSON Mode Request URI: 

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

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 "contact" resource, if any. See the list.
<parent> contact Array of Objects The contact object
contact contact_id Integer ID for contact
contact CHILD PROPERTY   Child properties to be edited *

* One or more contact child properties listed below are required in addition to "contact_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> contact Required Array of Objects The contact object
contact contact_id Optional Integer ID for contact
contact type Optional String Phone, SMS or Email (Use a V2 read command to retrieve the valid values)
contact destination Optional String Phone number, Email address, etc. of contact's destination
contact description Optional String Short description describing the destination ex: "Work Phone"
contact schedule Optional Object (See Sensaphone.net API/schedule)
contact enable Optional Boolean If the contact is enabled.

POST

POST will only be used for creating a new contact. The destination (phone number or email address) is required and the type automatically determined. If using the URI Mode Request the user can subsequently use PUT to edit the other sub-properties and/or change the type. Alternatively, this can be done in one step with the JSON Mode Request.

URI Mode Request URI:

  • Create a new user dependent contact.
  POST https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/contact/destination/{DESTINATION}
  • Create a new user independent contact.
  POST https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/contact/destination/{DESTINATION}

JSON Mode Request URI: 

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

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 "contact" resource, if any. See the list.
<parent> contact Array of Objects The contact object
contact destination String Phone number or Email address of Destination
contact CHILD PROPERTY   Additional child properties to be set *

* One or more contact child properties listed below may be specified in addition to "contact_id" and "destination".

JSON Mode Response Properties

Parent PropertyChild PropertyStatus Type Description
  <parent object(s)> Optional Array of Objects The parent(s) specified in the request.
<parent> contact Required Array of Objects The contact object
contact contact_id Optional Integer ID for contact
contact type Optional String Phone, SMS or Email (Use a V2 read command to retrieve the valid values)
contact destination Optional String Phone number, Email address, etc. of contact's destination
contact description Optional String Short description describing the destination ex: "Work Phone"
contact schedule Optional Object (See Sensaphone.net API/schedule)
contact enable Optional Boolean If the contact is enabled.

DELETE

URI Mode Request URI:

  • Delete a contact. To delete a contact, the ID of the contact to be deleted must be provided.
  DELETE https://rest.sensaphone.net/api/v1/{ACCTID}/{SESSIONID}/user/{USER_ID}/alarm_user/contact/{CONTACT_ID}

JSON Mode Request URI: 

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

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 "contact" resource, if any. See the list.
<parent> contact Array of Objects The contact object
contact contact_id Integer ID for contact
Retrieved from "https://wiki.sensaphone.net/index.php?title=Sensaphone.net_API/contact&oldid=61"