osapi.jive.corev3.people.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 with the most important data for a Person. See the table below for a list of all fields.

{
  "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"
}
Create Person

Read create() to learn how to create a new person.

Update Person Status

Use update() to update a person. By setting the status field, the person status will get updated and published in the activity stream.

Properties

PropertyTypeMode Description
addressesAddressesoptional
Postal 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.

emailsEmailsrequired
Email 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-only
Number 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.

jiveJiverequired
Jive 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-only
Date 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

Methods

createStream(streamentity,options)
POST /people/1234/streams

Retrieves

Stream

Description

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:
Options:
NameTypeRequiredDescription
fieldsStringfalseNames of the fields to be returned
Retrieves:
  • Stream
  • createTask(task,options)
    POST /people/1234/tasks

    Retrieves

    Task

    Description

    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:
    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Task
  • Since: 3.1
    destroy()
    DELETE /people/1234

    Retrieves

    --

    Description

    Delete this person and all content this person has created.

    get(options)
    GET /people/1234

    Retrieves

    Person

    Description

    Return an updated version of this person.

    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Person
  • getActivity(options)
    GET /people/1234/activities

    Retrieves

    Activity[]

    Description

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

    Options:
    NameTypeRequiredDescription
    afterStringfalseDate and time representing the minimum "last activity in a collection" timestamp for selecting activities. Cannot specify both after and before
    beforeStringfalseDate and time representing the maximum "last activity in a collection" timestamp for selecting activities. Cannot specify both after and before
    countIntegerfalseNumber of activities to be returned (you may get more activities than this in order to get all of the activities inthe last collection)
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Activity[]
  • getBlog(options)
    GET /people/1234/blog

    Retrieves

    Blog

    Description

    Return the blog for this person, if it exists.

    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Blog
  • getColleagues(options)
    GET /people/1234/@colleagues

    Retrieves

    Person[]

    Description

    Return a paginated list of colleagues of this person.

    Availability:

    Jive instance must be configured to support Organization Chart relationships.

    Options:
    NameTypeRequiredDescription
    countIntegerfalseNumber of colleagues to be returned
    fieldsStringfalseNames of the fields to be returned
    startIndexIntegerfalseZero-relative index of the first colleague to be returned
    Retrieves:
  • Person[]
  • getFollowers(options)
    GET /people/1234/@followers

    Retrieves

    Person[]

    Description

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

    Availability:

    Jive instance must be configured to support Organization Chart relationships.

    Options:
    NameTypeRequiredDescription
    countIntegerfalseNumber of followers to be returned (default is 25)
    fieldsStringfalseNames of the fields to be returned
    startIndexIntegerfalseZero-relative index of the first follower to be returned
    Retrieves:
  • Person[]
  • getFollowing(options)
    GET /people/1234/@following

    Retrieves

    Person[]

    Description

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

    Options:
    NameTypeRequiredDescription
    countIntegerfalseNumber of people to be returned (default is 25)
    fieldsStringfalseNames of the fields to be returned
    startIndexIntegerfalseZero-relative index of the first being-followed person to be returned
    Retrieves:
  • Person[]
  • getFollowingIn(options)
    GET /people/1234/followingIn

    Retrieves

    Stream[]

    Description

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

    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Stream[]
  • getImages(options)
    GET /people/1234/images

    Retrieves

    ProfileImage[]

    Description

    Return a list of profile images for the specified person.

    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • ProfileImage[]
  • getManager(options)
    GET /people/1234/@manager

    Retrieves

    Person

    Description

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

    Availability:

    Jive instance must be configured to support Organization Chart relationships.

    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Person
  • getMembers(options)
    GET /members/people/1234

    Retrieves

    Member[]

    Description

    Return a list of place memberships for this person.

    Options:
    NameTypeRequiredDescription
    countIntegerfalseMaximum number of memberships to be returned (default is 25)
    fieldsStringfalseNames of the fields to be returned
    startIndexIntegerfalseZero-relative offset of the first membership to be returned (default is 0)
    Retrieves:
  • Member[] describing the places this person is a member of, and the membership state
  • Since: 3.1
    getReports(options)
    GET /people/1234/@reports

    Retrieves

    Person[]

    Description

    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.

    Options:
    NameTypeRequiredDescription
    countIntegerfalseNumber of people to be returned (default is 25)
    fieldsStringfalseNames of the fields to be returned
    startIndexIntegerfalseZero-relative index of the first being-followed person to be returned
    Retrieves:
  • Person[]
  • getStreams(options)
    GET /people/1234/streams

    Retrieves

    Stream[]

    Description

    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.

    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Stream[]
  • getTasks(options)
    GET /people/1234/tasks

    Retrieves

    Content[]

    Description

    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.

    Options:
    NameTypeRequiredDescription
    countIntegerfalseMaximum number of tasks to be returned
    fieldsStringfalseNames of the fields to be returned
    startIndexIntegerfalseZero-relative index of the first task to be returned
    Retrieves:
  • Task[] personal tasks for this person
  • Since: 3.1
    toURI()

    Retrieves

    String

    Description

    Retrieves:
  • A URI representing this entity, or undefined if no such URI exists.
  • update(personentity)
    PUT /people/1234

    Retrieves

    Person

    Description

    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
    Options:
    NameTypeRequiredDescription
    fieldsStringfalseNames of the fields to be returned
    Retrieves:
  • Person reflecting the updated person
  • Resources

    ResourceMethodReturnsDescription
    avatarGETObject

    Return the bytes of the avatar image.

    htmlGETObject

    URI of the HTML user profile of this person.