REST Resource: people

Resource: Person

Information about a person merged from various data sources such as the authenticated user's contacts and profile data.

Most fields can have multiple items. The items in a field have no guaranteed order, but each non-empty field is guaranteed to have exactly one field with metadata.primary set to true.

JSON representation
{
  "resourceName": string,
  "etag": string,
  "metadata": {
    object(PersonMetadata)
  },
  "locales": [
    {
      object(Locale)
    }
  ],
  "names": [
    {
      object(Name)
    }
  ],
  "nicknames": [
    {
      object(Nickname)
    }
  ],
  "coverPhotos": [
    {
      object(CoverPhoto)
    }
  ],
  "photos": [
    {
      object(Photo)
    }
  ],
  "genders": [
    {
      object(Gender)
    }
  ],
  "ageRange": enum(AgeRange),
  "ageRanges": [
    {
      object(AgeRangeType)
    }
  ],
  "birthdays": [
    {
      object(Birthday)
    }
  ],
  "events": [
    {
      object(Event)
    }
  ],
  "addresses": [
    {
      object(Address)
    }
  ],
  "residences": [
    {
      object(Residence)
    }
  ],
  "emailAddresses": [
    {
      object(EmailAddress)
    }
  ],
  "phoneNumbers": [
    {
      object(PhoneNumber)
    }
  ],
  "imClients": [
    {
      object(ImClient)
    }
  ],
  "taglines": [
    {
      object(Tagline)
    }
  ],
  "biographies": [
    {
      object(Biography)
    }
  ],
  "urls": [
    {
      object(Url)
    }
  ],
  "organizations": [
    {
      object(Organization)
    }
  ],
  "occupations": [
    {
      object(Occupation)
    }
  ],
  "interests": [
    {
      object(Interest)
    }
  ],
  "skills": [
    {
      object(Skill)
    }
  ],
  "braggingRights": [
    {
      object(BraggingRights)
    }
  ],
  "relations": [
    {
      object(Relation)
    }
  ],
  "relationshipInterests": [
    {
      object(RelationshipInterest)
    }
  ],
  "relationshipStatuses": [
    {
      object(RelationshipStatus)
    }
  ],
  "memberships": [
    {
      object(Membership)
    }
  ],
  "userDefined": [
    {
      object(UserDefined)
    }
  ],
}
Fields
resourceName

string

The resource name for the person, assigned by the server. An ASCII string with a max length of 27 characters, in the form of people/person_id.

etag

string

The HTTP entity tag of the resource. Used for web cache validation.

metadata

object(PersonMetadata)

Read-only metadata about the person.

locales[]

object(Locale)

The person's locale preferences.

names[]

object(Name)

The person's names.

nicknames[]

object(Nickname)

The person's nicknames.

coverPhotos[]

object(CoverPhoto)

The person's read-only cover photos.

photos[]

object(Photo)

The person's read-only photos.

genders[]

object(Gender)

The person's genders.

ageRange
(deprecated)

enum(AgeRange)

DEPRECATED (Please use person.ageRanges instead)**

The person's read-only age range.

ageRanges[]

object(AgeRangeType)

The person's read-only age ranges.

birthdays[]

object(Birthday)

The person's birthdays.

events[]

object(Event)

The person's events.

addresses[]

object(Address)

The person's street addresses.

residences[]

object(Residence)

The person's residences.

emailAddresses[]

object(EmailAddress)

The person's email addresses.

phoneNumbers[]

object(PhoneNumber)

The person's phone numbers.

imClients[]

object(ImClient)

The person's instant messaging clients.

taglines[]

object(Tagline)

The person's read-only taglines.

biographies[]

object(Biography)

The person's biographies.

urls[]

object(Url)

The person's associated URLs.

organizations[]

object(Organization)

The person's past or current organizations.

occupations[]

object(Occupation)

The person's occupations.

interests[]

object(Interest)

The person's interests.

skills[]

object(Skill)

The person's skills.

braggingRights[]

object(BraggingRights)

The person's bragging rights.

relations[]

object(Relation)

The person's relations.

relationshipInterests[]

object(RelationshipInterest)

The person's read-only relationship interests.

relationshipStatuses[]

object(RelationshipStatus)

The person's read-only relationship statuses.

memberships[]

object(Membership)

The person's read-only group memberships.

userDefined[]

object(UserDefined)

The person's user defined data.

PersonMetadata

The read-only metadata about a person.

JSON representation
{
  "sources": [
    {
      object(Source)
    }
  ],
  "previousResourceNames": [
    string
  ],
  "linkedPeopleResourceNames": [
    string
  ],
  "deleted": boolean,
  "objectType": enum(ObjectType),
}
Fields
sources[]

object(Source)

The sources of data for the person.

previousResourceNames[]

string

Any former resource names this person has had. Populated only for connections.list requests that include a sync token.

The resource name may change when adding or removing fields that link a contact and profile such as a verified email, verified phone number, or profile URL.

linkedPeopleResourceNames[]

string

Resource names of people linked to this resource.

deleted

boolean

True if the person resource has been deleted. Populated only for connections.list requests that include a sync token.

objectType
(deprecated)

enum(ObjectType)

DEPRECATED (Please use person.metadata.sources.profileMetadata.objectType instead)

The type of the person object.

Source

The source of a field.

JSON representation
{
  "type": enum(SourceType),
  "id": string,
  "etag": string,
  "updateTime": string,
  "profileMetadata": {
    object(ProfileMetadata)
  },
}
Fields
type

enum(SourceType)

The source type.

id

string

The unique identifier within the source type generated by the server.

etag

string

Only populated in person.metadata.sources.

The HTTP entity tag of the source. Used for web cache validation.

updateTime

string (Timestamp format)

Only populated in person.metadata.sources.

Last update timestamp of this source.

A timestamp in RFC3339 UTC "Zulu" format, accurate to nanoseconds. Example: "2014-10-02T15:01:23.045123456Z".

profileMetadata

object(ProfileMetadata)

Only populated in person.metadata.sources.

Metadata about a source of type PROFILE.

SourceType

The type of a source.

Enums
SOURCE_TYPE_UNSPECIFIED Unspecified.
ACCOUNT Google Account.
PROFILE Google profile. You can view the profile at https://profiles.google.com/id where id is the source id.
DOMAIN_PROFILE Google Apps domain profile.
CONTACT Google contact. You can view the contact at https://contact.google.com/id where id is the source id.

ProfileMetadata

The read-only metadata about a profile.

JSON representation
{
  "objectType": enum(ObjectType),
  "userTypes": [
    enum(UserType)
  ],
}
Fields
objectType

enum(ObjectType)

The profile object type.

userTypes[]

enum(UserType)

The user types.

ObjectType

The type of a person object.

Enums
OBJECT_TYPE_UNSPECIFIED Unspecified.
PERSON Person.
PAGE Google+ Page.

UserType

The type of the user.

Enums
USER_TYPE_UNKNOWN The user type is not known.
GOOGLE_USER The user is a Google user.
GPLUS_USER The user is a Google+ user.
GOOGLE_APPS_USER The user is a Google Apps for Work user.

Locale

A person's locale preference.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "value": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the locale.

value

string

The well-formed IETF BCP 47 language tag representing the locale.

FieldMetadata

Metadata about a field.

JSON representation
{
  "primary": boolean,
  "verified": boolean,
  "source": {
    object(Source)
  },
}
Fields
primary

boolean

True if the field is the primary field; false if the field is a secondary field.

verified

boolean

True if the field is verified; false if the field is unverified. A verified field is typically a name, email address, phone number, or website that has been confirmed to be owned by the person.

source

object(Source)

The source of the field.

Name

A person's name. If the name is a mononym, the family name is empty.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "displayName": string,
  "displayNameLastFirst": string,
  "familyName": string,
  "givenName": string,
  "middleName": string,
  "honorificPrefix": string,
  "honorificSuffix": string,
  "phoneticFullName": string,
  "phoneticFamilyName": string,
  "phoneticGivenName": string,
  "phoneticMiddleName": string,
  "phoneticHonorificPrefix": string,
  "phoneticHonorificSuffix": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the name.

displayName

string

The read-only display name formatted according to the locale specified by the viewer's account or the Accept-Language HTTP header.

displayNameLastFirst

string

The read-only display name with the last name first formatted according to the locale specified by the viewer's account or the Accept-Language HTTP header.

familyName

string

The family name.

givenName

string

The given name.

middleName

string

The middle name(s).

honorificPrefix

string

The honorific prefixes, such as Mrs. or Dr.

honorificSuffix

string

The honorific suffixes, such as Jr.

phoneticFullName

string

The full name spelled as it sounds.

phoneticFamilyName

string

The family name spelled as it sounds.

phoneticGivenName

string

The given name spelled as it sounds.

phoneticMiddleName

string

The middle name(s) spelled as they sound.

phoneticHonorificPrefix

string

The honorific prefixes spelled as they sound.

phoneticHonorificSuffix

string

The honorific suffixes spelled as they sound.

Nickname

A person's nickname.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "value": string,
  "type": enum(NicknameType),
}
Fields
metadata

object(FieldMetadata)

Metadata about the nickname.

value

string

The nickname.

type

enum(NicknameType)

The type of the nickname.

NicknameType

The type of a nickname.

Enums
DEFAULT Generic nickname.
MAIDEN_NAME Maiden name or birth family name. Used when the person's family name has changed as a result of marriage.
INITIALS Initials.
GPLUS Google+ profile nickname.
OTHER_NAME A professional affiliation or other name; for example, Dr. Smith.

CoverPhoto

A person's read-only cover photo. A large image shown on the person's profile page that represents who they are or what they care about.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "url": string,
  "default": boolean,
}
Fields
metadata

object(FieldMetadata)

Metadata about the cover photo.

url

string

The URL of the cover photo.

default

boolean

True if the cover photo is the default cover photo; false if the cover photo is a user-provided cover photo.

Photo

A person's read-only photo. A picture shown next to the person's name to help others recognize the person.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "url": string,
  "default": boolean,
}
Fields
metadata

object(FieldMetadata)

Metadata about the photo.

url

string

The URL of the photo. You can change the desired size by appending a query parameter sz=size at the end of the url. Example: https://lh3.googleusercontent.com/-T_wVWLlmg7w/AAAAAAAAAAI/AAAAAAAABa8/00gzXvDBYqw/s100/photo.jpg?sz=50

default

boolean

True if the photo is a default photo; false if the photo is a user-provided photo.

Gender

A person's gender.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "value": string,
  "formattedValue": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the gender.

value

string

The gender for the person. The gender can be custom or predefined. Possible values include, but are not limited to, the following:

  • male
  • female
  • other
  • unknown

formattedValue

string

The read-only value of the gender translated and formatted in the viewer's account locale or the Accept-Language HTTP header locale.

AgeRange

DEPRECATED (Please use person.ageRanges instead)

An age range of a person.

Enums
AGE_RANGE_UNSPECIFIED Unspecified.
LESS_THAN_EIGHTEEN Younger than eighteen.
EIGHTEEN_TO_TWENTY Between eighteen and twenty.
TWENTY_ONE_OR_OLDER Twenty-one and older.

AgeRangeType

A person's age range.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "ageRange": enum(AgeRange),
}
Fields
metadata

object(FieldMetadata)

Metadata about the age range.

ageRange

enum(AgeRange)

The age range.

Birthday

A person's birthday. At least one of the date and text fields are specified. The date and text fields typically represent the same date, but are not guaranteed to.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "date": {
    object(Date)
  },
  "text": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the birthday.

date

object(Date)

The date of the birthday.

text

string

A free-form string representing the user's birthday.

Date

Represents a whole calendar date, for example a date of birth. The time of day and time zone are either specified elsewhere or are not significant. The date is relative to the Proleptic Gregorian Calendar. The day may be 0 to represent a year and month where the day is not significant. The year may be 0 to represent a month and day independent of year; for example, anniversary date.

JSON representation
{
  "year": number,
  "month": number,
  "day": number,
}
Fields
year

number

Year of date. Must be from 1 to 9999, or 0 if specifying a date without a year.

month

number

Month of year. Must be from 1 to 12.

day

number

Day of month. Must be from 1 to 31 and valid for the year and month, or 0 if specifying a year/month where the day is not significant.

Event

An event related to the person.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "date": {
    object(Date)
  },
  "type": string,
  "formattedType": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the event.

date

object(Date)

The date of the event.

type

string

The type of the event. The type can be custom or predefined. Possible values include, but are not limited to, the following:

  • anniversary
  • other

formattedType

string

The read-only type of the event translated and formatted in the viewer's account locale or the Accept-Language HTTP header locale.

Address

A person's physical address. May be a P.O. box or street address. All fields are optional.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "formattedValue": string,
  "type": string,
  "formattedType": string,
  "poBox": string,
  "streetAddress": string,
  "extendedAddress": string,
  "city": string,
  "region": string,
  "postalCode": string,
  "country": string,
  "countryCode": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the address.

formattedValue

string

The unstructured value of the address. If this is not set by the user it will be automatically constructed from structured values.

type

string

The type of the address. The type can be custom or predefined. Possible values include, but are not limited to, the following:

  • home
  • work
  • other

formattedType

string

The read-only type of the address translated and formatted in the viewer's account locale or the Accept-Language HTTP header locale.

poBox

string

The P.O. box of the address.

streetAddress

string

The street address.

extendedAddress

string

The extended address of the address; for example, the apartment number.

city

string

The city of the address.

region

string

The region of the address; for example, the state or province.

postalCode

string

The postal code of the address.

country

string

The country of the address.

countryCode

string

The ISO 3166-1 alpha-2 country code of the address.

Residence

A person's past or current residence.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "value": string,
  "current": boolean,
}
Fields
metadata

object(FieldMetadata)

Metadata about the residence.

value

string

The address of the residence.

current

boolean

True if the residence is the person's current residence; false if the residence is a past residence.

EmailAddress

A person's email address.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "value": string,
  "type": string,
  "formattedType": string,
  "displayName": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the email address.

value

string

The email address.

type

string

The type of the email address. The type can be custom or predefined. Possible values include, but are not limited to, the following:

  • home
  • work
  • other

formattedType

string

The read-only type of the email address translated and formatted in the viewer's account locale or the Accept-Language HTTP header locale.

displayName

string

The display name of the email.

PhoneNumber

A person's phone number.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "value": string,
  "canonicalForm": string,
  "type": string,
  "formattedType": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the phone number.

value

string

The phone number.

canonicalForm

string

The read-only canonicalized ITU-T E.164 form of the phone number.

type

string

The type of the phone number. The type can be custom or predefined. Possible values include, but are not limited to, the following:

  • home
  • work
  • mobile
  • homeFax
  • workFax
  • otherFax
  • pager
  • workMobile
  • workPager
  • main
  • googleVoice
  • other

formattedType

string

The read-only type of the phone number translated and formatted in the viewer's account locale or the Accept-Language HTTP header locale.

ImClient

A person's instant messaging client.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "username": string,
  "type": string,
  "formattedType": string,
  "protocol": string,
  "formattedProtocol": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the IM client.

username

string

The user name used in the IM client.

type

string

The type of the IM client. The type can be custom or predefined. Possible values include, but are not limited to, the following:

  • home
  • work
  • other

formattedType

string

The read-only type of the IM client translated and formatted in the viewer's account locale or the Accept-Language HTTP header locale.

protocol

string

The protocol of the IM client. The protocol can be custom or predefined. Possible values include, but are not limited to, the following:

  • aim
  • msn
  • yahoo
  • skype
  • qq
  • googleTalk
  • icq
  • jabber
  • netMeeting

formattedProtocol

string

The read-only protocol of the IM client formatted in the viewer's account locale or the Accept-Language HTTP header locale.

Tagline

A read-only brief one-line description of the person.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "value": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the tagline.

value

string

The tagline.

Biography

A person's short biography.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "value": string,
  "contentType": enum(ContentType),
}
Fields
metadata

object(FieldMetadata)

Metadata about the biography.

value

string

The short biography.

contentType

enum(ContentType)

The content type of the biography.

ContentType

The type of content.

Enums
CONTENT_TYPE_UNSPECIFIED Unspecified.
TEXT_PLAIN Plain text.
TEXT_HTML HTML text.

Url

A person's associated URLs.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "value": string,
  "type": string,
  "formattedType": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the URL.

value

string

The URL.

type

string

The type of the URL. The type can be custom or predefined. Possible values include, but are not limited to, the following:

  • home
  • work
  • blog
  • profile
  • homePage
  • ftp
  • reservations
  • appInstallPage: website for a Google+ application.
  • other

formattedType

string

The read-only type of the URL translated and formatted in the viewer's account locale or the Accept-Language HTTP header locale.

Organization

A person's past or current organization. Overlapping date ranges are permitted.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "type": string,
  "formattedType": string,
  "startDate": {
    object(Date)
  },
  "endDate": {
    object(Date)
  },
  "current": boolean,
  "name": string,
  "phoneticName": string,
  "department": string,
  "title": string,
  "jobDescription": string,
  "symbol": string,
  "domain": string,
  "location": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the organization.

type

string

The type of the organization. The type can be custom or predefined. Possible values include, but are not limited to, the following:

  • work
  • school

formattedType

string

The read-only type of the organization translated and formatted in the viewer's account locale or the Accept-Language HTTP header locale.

startDate

object(Date)

The start date when the person joined the organization.

endDate

object(Date)

The end date when the person left the organization.

current

boolean

True if the organization is the person's current organization; false if the organization is a past organization.

name

string

The name of the organization.

phoneticName

string

The phonetic name of the organization.

department

string

The person's department at the organization.

title

string

The person's job title at the organization.

jobDescription

string

The person's job description at the organization.

symbol

string

The symbol associated with the organization; for example, a stock ticker symbol, abbreviation, or acronym.

domain

string

The domain name associated with the organization; for example, google.com.

location

string

The location of the organization office the person works at.

Occupation

A person's occupation.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "value": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the occupation.

value

string

The occupation; for example, carpenter.

Interest

One of the person's interests.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "value": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the interest.

value

string

The interest; for example, stargazing.

Skill

A skill that the person has.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "value": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the skill.

value

string

The skill; for example, underwater basket weaving.

BraggingRights

A person's bragging rights.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "value": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the bragging rights.

value

string

The bragging rights; for example, climbed mount everest.

Relation

A person's relation to another person.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "person": string,
  "type": string,
  "formattedType": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the relation.

person

string

The name of the other person this relation refers to.

type

string

The person's relation to the other person. The type can be custom or predefined. Possible values include, but are not limited to, the following values:

  • spouse
  • child
  • mother
  • father
  • parent
  • brother
  • sister
  • friend
  • relative
  • domesticPartner
  • manager
  • assistant
  • referredBy
  • partner

formattedType

string

The type of the relation translated and formatted in the viewer's account locale or the locale specified in the Accept-Language HTTP header.

RelationshipInterest

A person's read-only relationship interest .

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "value": string,
  "formattedValue": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the relationship interest.

value

string

The kind of relationship the person is looking for. The value can be custom or predefined. Possible values include, but are not limited to, the following values:

  • friend
  • date
  • relationship
  • networking

formattedValue

string

The value of the relationship interest translated and formatted in the viewer's account locale or the locale specified in the Accept-Language HTTP header.

RelationshipStatus

A person's read-only relationship status.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "value": string,
  "formattedValue": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the relationship status.

value

string

The relationship status. The value can be custom or predefined. Possible values include, but are not limited to, the following:

  • single
  • inARelationship
  • engaged
  • married
  • itsComplicated
  • openRelationship
  • widowed
  • inDomesticPartnership
  • inCivilUnion

formattedValue

string

The read-only value of the relationship status translated and formatted in the viewer's account locale or the Accept-Language HTTP header locale.

Membership

A person's read-only membership in a group.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },

  // Union field membership can be only one of the following:
  "contactGroupMembership": {
    object(ContactGroupMembership)
  },
  "domainMembership": {
    object(DomainMembership)
  },
  // End of list of possible types for union field membership.
}
Fields
metadata

object(FieldMetadata)

Metadata about the membership.

Union field membership. The membership. membership can be only one of the following:
contactGroupMembership

object(ContactGroupMembership)

The contact group membership.

domainMembership

object(DomainMembership)

The domain membership.

ContactGroupMembership

A Google contact group membership.

JSON representation
{
  "contactGroupId": string,
}
Fields
contactGroupId

string

The contact group ID for the contact group membership. The contact group ID can be custom or predefined. Possible values include, but are not limited to, the following:

  • myContacts
  • starred
  • A numerical ID for user-created groups.

DomainMembership

A Google Apps Domain membership.

JSON representation
{
  "inViewerDomain": boolean,
}
Fields
inViewerDomain

boolean

True if the person is in the viewer's Google Apps domain.

UserDefined

Arbitrary user data that is populated by the end users.

JSON representation
{
  "metadata": {
    object(FieldMetadata)
  },
  "key": string,
  "value": string,
}
Fields
metadata

object(FieldMetadata)

Metadata about the user defined data.

key

string

The end user specified key of the user defined data.

value

string

The end user specified value of the user defined data.

Methods

createContact

Create a new contact and return the person resource for that contact.

deleteContact

Delete a contact person.

get

Provides information about a person by specifying a resource name.

getBatchGet

Provides information about a list of specific people by specifying a list of requested resource names.

updateContact

Update contact data for an existing contact person.