Person

A Person represents a Jive user in a style that is as consistent as possible with the OpenSocial specification for a Person object. The JSON representation of a Person has several fields for information about emails, phone numbers, etc. More information about these fields can be found here:

  • Addresses - collection of a Jive user's physical addresses
  • Emails - collection of a Jive user's emails
  • Jive - Jive extensions to a Person object (level, username, external contributor, etc.)
  • Level - status level of a Jive user
  • Name - contains first name, last name, and formatted name
  • PhoneNumbers - collection of a Jive user's phone numbers
  • Photos - collection of URIs to a Jive user's profile images
  • Profile - profile information besides addresses, emails, phone numbers, and locations
  • ProfileImage - a Jive user's profile image
  • Update - status update of a Jive user or place

Examples:
Example JSON

JSON including important fields and a Person's resources. See the tables below for a list of all fields and resources.

{
  "name" : {
    "formatted" : "Administrator"
  },
  "type" : "person",
  "status" : "My new status",
  "displayName" : "Administrator",
  "jive" : {
    "level" : {
      "name" : "Scout",
      "points" : 582
    },
    "profile" : [ {
      "value" : "Master of puppets",
      "jive_label" : "Title"
    }, {
      "value" : "Support",
      "jive_label" : "Department"
    }, {
      "value" : "ACME Inc.",
      "jive_label" : "Company"
    }, {
      "value" : "09/05/2001",
      "jive_label" : "Hire Date"
    }, {
      "value" : "I was born in Earth.",
      "jive_label" : "Biography"
    }, {
      "value" : "Expert in this and that.",
      "jive_label" : "Expertise"
    } ],
    "username" : "admin",
    "external" : false,
    "visible" : true,
    "enabled" : true,
    "externalContributor" : false,
    "federated" : false
  },
  "emails" : [ {
    "value" : "admin@example.com",
    "type" : "work",
    "jive_label" : "Email",
    "primary" : true
  } ],
  "addresses" : [ {
    "value" : {
      "streetAddress" : "915 SW Stark St",
      "locality" : "Portland",
      "region" : "Oregon",
      "postalCode" : "97205",
      "country" : "USA",
      "formatted" : "915 SW Stark St\nPortland Oregon 97205\nUSA"
    },
    "jive_label" : "Address",
    "primary" : true
  } ],
  "phoneNumbers" : [ {
    "value" : "503.972.6655",
    "jive_label" : "Phone Number",
    "primary" : true
  }, {
    "value" : "503.972.6644",
    "jive_label" : "Mobile Phone Number"
  } ],
  "photos" : [ {
    "value" : "https://example.jiveon.com/api/core/v3/people/1/images/1/data"
  } ],
  "thumbnailUrl" : "https://example.jiveon.com/api/core/v3/people/1/avatar",
  "followerCount" : 0,
  "followingCount" : 4,
  "published" : "2012-05-14T19:12:10.061+0000",
  "updated" : "2012-07-15T19:57:17.009+0000",
  "id" : "1",
  "resources" : {
    "reports" : {
      "ref" : "https://example.jiveon.com/api/core/v3/people/1/@reports",
      "allowed" : [ "GET" ]
    },
    "manager" : {
      "ref" : "https://example.jiveon.com/api/core/v3/people/1/@manager",
      "allowed" : [ "GET" ]
    },
    "self" : {
      "ref" : "https://example.jiveon.com/api/core/v3/people/1",
      "allowed" : [ "PUT", "DELETE", "GET" ]
    },
    "avatar" : {
      "ref" : "https://example.jiveon.com/api/core/v3/people/1/avatar",
      "allowed" : [ "GET" ]
    },
    "blog" : {
      "ref" : "https://example.jiveon.com/api/core/v3/people/1/blog",
      "allowed" : [ "GET" ]
    },
    "colleagues" : {
      "ref" : "https://example.jiveon.com/api/core/v3/people/1/@colleagues",
      "allowed" : [ "GET" ]
    },
    "followers" : {
      "ref" : "https://example.jiveon.com/api/core/v3/people/1/@followers",
      "allowed" : [ "GET" ]
    },
    "following" : {
      "ref" : "https://example.jiveon.com/api/core/v3/people/1/@following",
      "allowed" : [ "GET" ]
    },
    "images" : {
      "ref" : "https://example.jiveon.com/api/core/v3/people/1/images",
      "allowed" : [ "POST", "GET" ]
    },
    "html" : {
      "ref" : "https://example.jiveon.com/people/admin",
      "allowed" : [ "GET" ]
    },
    "streams" : {
      "ref" : "https://example.jiveon.com/api/core/v3/people/1/streams",
      "allowed" : [ "POST", "GET" ]
    },
    "followingIn" : {
      "ref" : "https://example.jiveon.com/api/core/v3/people/1/followingIn",
      "allowed" : [ "GET" ]
    },
    "tasks" : {
      "ref" : "https://example.jiveon.com/api/core/v3/people/1/tasks",
      "allowed" : [ "POST", "GET" ]
    },
    "activity" : {
      "ref" : "https://example.jiveon.com/api/core/v3/people/1/activities",
      "allowed" : [ "GET" ]
    }
  }
}
Get a person's group memberships
Perform a GET request to /members/people/{person_id}. This URL can be obtained from the members resource of a Person. See the resources table below.
curl -u admin:admin "http://example.jiveon.com/api/core/v3/members/people/1234"
Create Person

POST to /people creates a new person. The minimum set of fields you must include are:

 {
   "emails" : [ {
       "value" : "{emailAddress}",
       "jive_label" : "Email"
   } ],
   "jive" : {
       "password" : "{password}",
       "username" : "{username}"
   },
   "name" : {
       "familyName" : "{lastName}",
       "givenName" : "{firstName}"
   }
 }
Update Person Status

PUT to /people/{personID} updates a person. By setting the status field, the person status will get updated and published in the activity stream.

Add Profile Image

This is a two steps operation. First, POST to /profileImages/temporary to upload the image that will be used in the next step. Here we see a curl example:

 curl -i -u some_user -F "file1=@myNewLook.png;type=image/png" https://example.jiveon.com/api/core/v3/profileImages/temporary

Pay attention to the location header in the response since we are going to need it for the next step. The second step consists of a POST to /people/{personID}/images where the location header of the previous response will be sent as an HTML form param named imageURI. Here we can see a curl example:

 curl -i -u admin:admin --data "imageURI=https://example.jiveon.com/api/core/v3/profileImages/temporary/tempImage442646.bin" https://example.jiveon.com/api/core/v3/people/2001/images

Fields

FieldTypeMode Description
addressesAddressesoptionalPostal addresses belonging to this person, with standard types home,other,pobox,work and value type of address
Availability:

This person has at least one postal address visible to you.

displayNameStringread-only

Formatted full name of this person, suitable for use in UI presentation. If the person has privacy settings that do not allow you to see his or her name, this will be the Jive username instead.

emailsEmailsrequiredEmail addresses belonging to this person, with standard types home,other,work and value type of string.
Availability:

This person has at least one email address visible to you.

followerCountIntegerread-only

Number of people following this object.

Availability:

Will be present only for object types that support being followed.

followingCountIntegerread-onlyNumber of people this person is following.
idStringread-only

Identifier (unique within an object type and Jive instance) of this object. This field is internal to Jive and should not be confused with contentID or placeID used in URIs.

jiveJiverequiredJive extensions to OpenSocial person object.
locationStringoptional

Geographic location of this person.

nameNamerequired

Name components for this person.

phoneNumbersPhoneNumbersoptional

Phone numbers belonging to this person, with standard types: fax, home, mobile, other, pager, work.

Availability:

This person has at least one phone number visible to you.

photosPhotosread-only

URI(s) of profile images for this person. To manage profile images in REST, use the images resource.

Availability:

Jive instance must be configured to support profile images.

publishedISO 8601 Dateread-onlyDate and time when this person was originally created.

Availability:

Visible only to Jive admins or on your own person object.

resourcesObjectread-only

Resource links (and related permissions for the requesting person) relevant to this object.

statusStringoptional

Most recent status update for this person. Updating the status of a person this way, will not let you include images. If you need to include images then try creating an Update content.

tagsString[]optional

Defined tags for this person.

Availability:

Tags have been defined by this person, and are visible to you.

thumbnailIdStringread-only

Unique ID of the thumbnail (avatar) image for this person. This extra information can be used when clients are caching thumbnails but still want to miss the cache and get the new thumbnail.

Since: 3.2
thumbnailUrlStringread-only

URL of the thumbnail (avatar) image for this person.

typeStringread-only

The object type of this object ("person").

updatedISO 8601 Dateread-only

Date and time this person was most recently updated.

→ Fields used by update and create operations
→ Fields used only by create operations
→ Fields not used by update or create operations

Resources

ResourceMethodDescription
activityGET

Return a paginated list of activity stream entries for the specified person.

Retrieves:
  • Activity[]
  • avatarGET

    Return the bytes of the avatar image.

    blogGET

    Return the blog for this person, if it exists.

    Retrieves:
  • Blog
  • colleaguesGET

    Return a paginated list of colleagues of this person.

    Availability:

    Jive instance must be configured to support Organization Chart relationships.

    Retrieves:
  • Person[]
  • followersGET

    Return a paginated list of the people following the specified person.

    Availability:

    Jive instance must be configured to support Organization Chart relationships.

    Retrieves:
  • Person[]
  • followingGET

    Return a paginated list of the people that the specified person is following.

    Retrieves:
  • Person[]
  • followingInGET

    Return a list of Streams in which the requesting user is following the specified person (if any).

    Retrieves:
  • Stream[]
  • htmlGET

    URI of the HTML user profile of this person.

    imagesGET

    Return a list of profile images for the specified person.

    Retrieves:
  • ProfileImage[]
  • managerGET

    Return the person that is the manager of the specified person.

    Availability:

    Jive instance must be configured to support Organization Chart relationships.

    Retrieves:
  • Person
  • membersGET

    Return a list of place memberships for this person.

    Retrieves:
  • Member[] describing the places this person is a member of, and the membership state
  • Since: 3.1
    reportsGET

    Return a paginated list of the people that are direct reports of the specified person.

    Availability:

    Jive instance must be configured to support Organization Chart relationships.

    Retrieves:
  • Person[]
  • selfGET

    Return an updated version of this person.

    Retrieves:
  • Person
  • selfPUT

    Update the specified person, and return an updated Person describing him or her after the update has been completed.

    Takes:
    • Person containing the updated information
    Retrieves:
  • Person reflecting the updated person
  • selfDELETE

    Delete this person and all content this person has created.

    streamsPOST

    Create a new custom stream for the specified user. The minimum information required is:

         {
             "name" : "{name}"
         }
     

    Custom stream names must be unique per person, and there is a configurable limit on the number of custom streams that a particular person can create (default limit is 10).

    Availability:

    Available only when the specified person is also the requesting person.

    Takes:
    Retrieves:
  • Stream
  • streamsGET

    Return a list of the custom (and standard) activity streams for the specified person.

    Availability:

    Available only when the specified person is also the requesting person.

    Retrieves:
  • Stream[]
  • tasksPOST

    Create a new personal task for the specified user. The minimum information required is:

     {
      "subject": "Clean the carpet",
      "dueDate" : "2013-07-12T06:59:59.999+0000",
      "type": "task"
     }
     
    Availability:

    Available only when the specified person is also the requesting person.

    Takes:
    Retrieves:
  • Task
  • Since: 3.1
    tasksGET

    Return the first page of a paginated list of tasks for this person.

    Availability:

    Available only when the specified person is also the requesting person.

    Retrieves:
  • Task[] personal tasks for this person
  • Since: 3.1