University of Cambridge Person API

Methods for querying and manipulating people. #### Notes on the fetch parameter All methods that return people, institutions or groups also accept an optional `fetch` parameter that may be used to request additional information about the entities returned. Without this parameter, only a few basic details about each person, institution or group are returned. The `fetch` parameter is quite flexible, and may be used in a number of different ways: * **Attribute fetching**. Attributes may be fetched by specifying the `schemeid` of an attribute scheme. For example to fetch a person's email addresses, use the value `"email"`. For people common attribute schemes include `"jpegPhoto"`, `"misAffiliation"`, `"title"`, `"universityPhone"`, `"landlinePhone"`, `"mobilePhone"`, `"pager"`, `"labeledURI"` and `"address"`. The full list of person attribute schemes may be obtained using `#allAttributeSchemes`. * **Pseudo-attributes**. Certain special pseudo-attributes are defined for convenience. For people, the following pseudo-attributes are supported: * `"phone_numbers"` - fetches all phone numbers. This is equivalent to `"universityPhone,instPhone,landlinePhone,mobilePhone,pager"`. * `"all_identifiers"` - fetches all identifiers. Currently people only have CRSid identifiers, but in the future additional identifiers such as USN or staffNumber may be added. * `"all_attrs"` - fetches all attributes from all person attribute schemes. This does not include identifiers or references. * **Reference fetching**. For people, the following references are supported (and will fetch only non-cancelled institutions and groups): * `"all_insts"` - fetches all the institutions to which the person belongs (sorted in name order). * `"all_groups"` - fetches all the groups that the person is a member of, including indirect group memberships, via groups that include other groups. * `"direct_groups"` - fetches all the groups that the person is directly a member of. This does not include indirect group memberships - i.e., groups that include these groups. * **Chained reference fetching**. To fetch properties of referenced objects, the "dot" notation may be used. For example, to fetch the email addresses of all the institutions to which a person belongs, use `"all_insts.email"`. Chains may include a number of reference following steps, for example `"all_insts.managed_by_groups.all_members.email"` will fetch all the institutions to which the person belongs, all the groups that manage those institutions, all the visible members of those groups and all the email addresses of those managing group members. For more information about what can be fetched from referenced institutions and groups, refer to the documentation for `InstitutionMethods` and `GroupMethods`. Multiple values of the `fetch` parameter should be separated by commas. #### Fetch parameter examples `fetch = "email"` This fetches all the person's email addresses. `fetch = "title,address"` This fetches all the person's titles (roles) and addresses. `fetch = "all_attrs"` This fetches all the person's attributes. `fetch = "all_groups,all_insts"` This fetches all the groups and institutions to which the person belongs. `fetch = "all_insts.parent_insts"` This fetches all the person's institutions, and their parent institutions. `fetch = "all_insts.email,all_insts.all_members.email"` This fetches all the person's institutions and their email addresses, and all the members of those institutions, and the email addresses of all those members.