openapi: 3.0.0
info:
title: Lookup/Ibis web service group person API
version: '1.2'
description: "Methods for querying and manipulating groups.\n\n#### The fetch parameter for groups\n\nAll methods that return groups also accept an optional `fetch`\nparameter that may be used to request additional information about the\ngroups returned. For more details about the general rules that apply to\nthe `fetch` parameter, refer to the `PersonMethods`\ndocumentation.\n\nFor groups the `fetch` parameter may be used to fetch references\nto people, institutions or other groups. In each case, only non-cancelled\npeople, institutions and groups will be included when fetching references.\nThe following references are supported:\n\n* `\"all_members\"` - fetches all the people who are members of the\n group, including members of groups included by the group, and groups\n included by those groups, and so on.\n\n* `\"direct_members\"` - fetches all the people who are direct\n members of the group, not taking into account any included groups.\n\n* `\"members_of_inst\"` - if the group is a membership group for an\n institution, this fetches that institution.\n\n* `\"owning_insts\"` - fetches all the institutions to which the\n group belongs.\n\n* `\"manages_insts\"` - fetches all the institutions that the group\n manages. Typically this only applies to \"Editor\" groups.\n\n* `\"manages_groups\"` - fetches all the groups that this group\n manages. Note that some groups are self-managed, so this may be a\n self-reference.\n\n* `\"managed_by_groups\"` - fetches all the groups that manage this\n group.\n\n* `\"reads_groups\"` - fetches all the groups that this group has\n privileged access to. This means that members of this group can see the\n members of the referenced groups regardless of the membership visibility\n settings.\n\n* `\"read_by_groups\"` - fetches all the groups that have privileged\n access to this group.\n\n* `\"includes_groups\"` - fetches all the groups included by this\n group.\n\n* `\"included_by_groups\"` - fetches all the groups that include\n this group.\n\nAs with person `fetch` parameters, the references may be used\nin a chain by using the \"dot\" notation to fetch additional information\nabout referenced people, institutions or groups. For example\n`\"all_members.email\"` will fetch the email addresses of all members\nof the group. For more information about what can be fetched from\nreferenced people and institutions, refer to the documentation for\n`PersonMethods` and `InstitutionMethods`."
servers:
- url: https://lookup-test.srv.uis.cam.ac.uk/api/v1
description: Test server
- url: https://www.lookup.cam.ac.uk/api/v1
description: Live server
security:
- basicAuth: []
tags:
- name: person
description: "Methods for querying and manipulating people.\n\n#### Notes on the fetch parameter\n\nAll methods that return people, institutions or groups also accept an\noptional `fetch` parameter that may be used to request\nadditional information about the entities returned. Without this\nparameter, only a few basic details about each person, institution or\ngroup are returned. The `fetch` parameter is quite flexible,\nand may be used in a number of different ways:\n\n* **Attribute fetching**. Attributes may be fetched by specifying the\n `schemeid` of an attribute scheme. For example to fetch a\n person's email addresses, use the value `\"email\"`. For people common\n attribute schemes include `\"jpegPhoto\"`, `\"misAffiliation\"`,\n `\"title\"`, `\"universityPhone\"`, `\"landlinePhone\"`,\n `\"mobilePhone\"`, `\"pager\"`, `\"labeledURI\"` and `\"address\"`.\n The full list of person attribute schemes may be obtained using `#allAttributeSchemes`.\n\n* **Pseudo-attributes**. Certain special pseudo-attributes are defined\n for convenience. For people, the following pseudo-attributes are supported:\n\n * `\"phone_numbers\"` - fetches all phone numbers. This is\n equivalent to\n `\"universityPhone,instPhone,landlinePhone,mobilePhone,pager\"`.\n\n * `\"all_identifiers\"` - fetches all identifiers. Currently people\n only have CRSid identifiers, but in the future additional identifiers such\n as USN or staffNumber may be added.\n\n * `\"all_attrs\"` - fetches all attributes from all person attribute\n schemes. This does not include identifiers or references.\n\n* **Reference fetching**. For people, the following references are\n supported (and will fetch only non-cancelled institutions and groups):\n\n * `\"all_insts\"` - fetches all the institutions to which the person\n belongs (sorted in name order).\n\n * `\"all_groups\"` - fetches all the groups that the person is a\n member of, including indirect group memberships, via groups that include\n other groups.\n\n * `\"direct_groups\"` - fetches all the groups that the person is\n directly a member of. This does not include indirect group memberships -\n i.e., groups that include these groups.\n\n* **Chained reference fetching**. To fetch properties of referenced\n objects, the \"dot\" notation may be used. For example, to fetch the email\n addresses of all the institutions to which a person belongs, use\n `\"all_insts.email\"`. Chains may include a number of reference\n following steps, for example\n `\"all_insts.managed_by_groups.all_members.email\"` will fetch all the\n institutions to which the person belongs, all the groups that manage those\n institutions, all the visible members of those groups and all the email\n addresses of those managing group members. For more information about what\n can be fetched from referenced institutions and groups, refer to the\n documentation for `InstitutionMethods` and `GroupMethods`.\n\nMultiple values of the `fetch` parameter should be separated\nby commas.\n\n#### Fetch parameter examples\n\n`fetch = \"email\"`\nThis fetches all the person's email addresses.\n\n`fetch = \"title,address\"`\nThis fetches all the person's titles (roles) and addresses.\n\n`fetch = \"all_attrs\"`\nThis fetches all the person's attributes.\n\n`fetch = \"all_groups,all_insts\"`\nThis fetches all the groups and institutions to which the person belongs.\n\n`fetch = \"all_insts.parent_insts\"`\nThis fetches all the person's institutions, and their parent institutions.\n\n`fetch = \"all_insts.email,all_insts.all_members.email\"`\nThis fetches all the person's institutions and their email addresses, and\nall the members of those institutions, and the email addresses of all\nthose members."
paths:
/person/all-attr-schemes:
get:
tags:
- person
summary: Return a list of all the person attribute schemes available.
description: 'Return a list of all the person attribute schemes available. The
`schemeid` values of these schemes may be used in the
`fetch` parameter of other methods that return people.
NOTE: Some of these attribute schemes are not currently used (no
people have attribute values in the scheme). These schemes are
reserved for possible future use.'
operationId: Person_allAttributeSchemes
responses:
200:
description: 'All the available person attribute schemes (in precedence
order).'
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
attributeSchemes:
type: array
items:
$ref: '#/components/schemas/AttributeScheme'
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/person/all-people:
get:
tags:
- person
summary: Return a list of all people (in batches).
description: 'Return a list of all people (in batches).
The results are sorted by identifier, starting with the first person
after the person with the specified identifier. Thus, to iterate over
all people, pass a `null` identifier to get the first batch of
people, then pass the last identifier from the previous batch to get
the next batch, and repeat until no more people are returned.
By default, only a few basic details about each person are returned,
but the optional `fetch` parameter may be used to fetch
additional attributes or references.'
operationId: Person_allPeople
parameters:
- name: includeCancelled
in: query
description: 'Flag to allow cancelled people to
be included (people who are no longer members of the University).
Defaults to `false`.'
required: false
schema:
type: boolean
- name: identifier
in: query
description: 'The identifier (CRSid) of the person to
start after, or `null` to start from the first person.'
required: false
schema:
type: string
- name: limit
in: query
description: 'The maximum number of people to return.
Defaults to 100.'
required: false
schema:
type: integer
format: int32
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch.'
required: false
schema:
type: string
responses:
200:
description: The requested people (in identifier order).
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
people:
type: array
items:
$ref: '#/components/schemas/Person'
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/person/list:
get:
tags:
- person
summary: Get the people with the specified identifiers (typically CRSids).
description: 'Get the people with the specified identifiers (typically CRSids).
Each identifier may be either a CRSid, or an identifier from another
identifier scheme, prefixed with that scheme''s name and a slash. For
example `"mug99"` or `"usn/123456789"`.
By default, only a few basic details about each person are returned,
but the optional `fetch` parameter may be used to fetch
additional attributes or references.
The results are sorted by identifier scheme and value.
NOTE: The number of people that may be fetched in a single call is
limited by the URL path length limit (around 8000 characters). A
CRSid is up to 7 characters long, and other identifiers are typically
longer, since they must also include the identifier scheme. Thus the
number of people that this method may fetch is typically limited to a
few hundred.
NOTE: The people returned may include cancelled people. It is the
caller''s repsonsibility to check their cancelled flags.'
operationId: Person_listPeople
parameters:
- name: crsids
in: query
description: 'A comma-separated list of identifiers. The name
of the query parameter reflects a time when only crsids were used with
lookup. Alternate schemes can be specified as noted above.'
required: true
schema:
type: string
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch.'
required: false
schema:
type: string
responses:
200:
description: The requested people (in identifier order).
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
people:
type: array
items:
$ref: '#/components/schemas/Person'
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/person/modified-people:
get:
tags:
- person
summary: Find all people modified between the specified pair of transactions.
description: 'Find all people modified between the specified pair of transactions.
The transaction IDs specified should be the IDs from two different
requests for the last (most recent) transaction ID, made at different
times, that returned different values, indicating that some Lookup
data was modified in the period between the two requests. This method
then determines which (if any) people were affected.
By default, only a few basic details about each person are returned,
but the optional `fetch` parameter may be used to fetch
additional attributes or references.
NOTE: All data returned reflects the latest available data about each
person. It is not possible to query for old data, or more detailed
information about the specific changes made.'
operationId: Person_modifiedPeople
parameters:
- name: minTxId
in: query
description: 'Include modifications made in transactions
after (but not including) this one.'
required: true
schema:
type: integer
format: int64
- name: maxTxId
in: query
description: 'Include modifications made in transactions
up to and including this one.'
required: true
schema:
type: integer
format: int64
- name: crsids
in: query
description: 'Only include people with identifiers in this
list. By default, all modified people will be included.'
required: false
schema:
type: string
- name: includeCancelled
in: query
description: 'Include cancelled people (people
who are no longer members of the University). By default, cancelled
people are excluded.'
required: false
schema:
type: boolean
- name: membershipChanges
in: query
description: 'Include people whose group or
institutional memberships have changed. By default, only people whose
attributes have been directly modified are included.'
required: false
schema:
type: boolean
- name: instNameChanges
in: query
description: 'Include people who are members of
instituions whose names have changed. This will also cause people
whose group or institutional memberships have changed to be included.
By default, changes to institution names do not propagate to people.'
required: false
schema:
type: boolean
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch.'
required: false
schema:
type: string
responses:
200:
description: The modified people (in identifier order).
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
people:
type: array
items:
$ref: '#/components/schemas/Person'
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/person/search:
get:
tags:
- person
summary: Search for people using a free text query string.
description: 'Search for people using a free text query string. This is the same
search function that is used in the Lookup web application.
By default, only a few basic details about each person are returned,
but the optional `fetch` parameter may be used to fetch
additional attributes or references.
NOTE: If the query string starts with the prefix `"person:"`, it
is treated as an [LQL query](/lql), allowing
more advanced searches. An LQL query will ignore the
`approxMatches` and `attributes` parameters, but
it will respect the values of `includeCancelled` and
`misStatus`. In addition, an LQL query will ignore the
`orderBy` parameter, since LQL queries always return
results in ID order.'
operationId: Person_search
parameters:
- name: query
in: query
description: The search string.
required: true
schema:
type: string
- name: approxMatches
in: query
description: 'Flag to enable more approximate
matching in the search, causing more results to be returned. Defaults
to `false`. This is ignored for LQL queries.'
required: false
schema:
type: boolean
- name: includeCancelled
in: query
description: 'Flag to allow cancelled people to
be included (people who are no longer members of the University).
Defaults to `false`.'
required: false
schema:
type: boolean
- name: misStatus
in: query
description: "The type of people to search for. This may\nbe\n\n* `\"staff\"` - only include people whose MIS status is\n `\"\"` (empty string), `\"staff\"`, or\n `\"staff,student\"`.\n\n* `\"student\"` - only include people whose MIS status is set to\n `\"student\"` or `\"staff,student\"`.\n\nOtherwise all matching people will be included (the default). Note\nthat the `\"staff\"` and `\"student\"` options are not\nmutually exclusive."
required: false
schema:
type: string
- name: attributes
in: query
description: 'A comma-separated list of attributes to
consider when searching. If this is `null` (the default) then
all attribute schemes marked as searchable will be included. This is
ignored for LQL queries.'
required: false
schema:
type: string
- name: offset
in: query
description: 'The number of results to skip at the start
of the search. Defaults to 0.'
required: false
schema:
type: integer
format: int32
- name: limit
in: query
description: 'The maximum number of results to return.
Defaults to 100.'
required: false
schema:
type: integer
format: int32
- name: orderBy
in: query
description: 'The order in which to list the results.
This may be either `"identifier"` or `"surname"` (the
default for non-LQL queries). This is ignored for LQL queries, which
always return results in identifier order.'
required: false
schema:
type: string
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch.'
required: false
schema:
type: string
responses:
200:
description: The matching people.
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
people:
type: array
items:
$ref: '#/components/schemas/Person'
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/person/search-count:
get:
tags:
- person
summary: 'Count the number of people that would be returned by a search using
a free text query string.'
description: 'Count the number of people that would be returned by a search using
a free text query string.
NOTE: If the query string starts with the prefix `"person:"`, it
is treated as an [LQL query](/lql), allowing
more advanced searches. An LQL query will ignore the
`approxMatches` and `attributes` parameters, but
it will respect the values of `includeCancelled` and
`misStatus`.'
operationId: Person_searchCount
parameters:
- name: query
in: query
description: The search string.
required: true
schema:
type: string
- name: approxMatches
in: query
description: 'Flag to enable more approximate
matching in the search, causing more results to be returned. Defaults
to `false`. This is ignored for LQL queries.'
required: false
schema:
type: boolean
- name: includeCancelled
in: query
description: 'Flag to allow cancelled people to
be included (people who are no longer members of the University).
Defaults to `false`.'
required: false
schema:
type: boolean
- name: misStatus
in: query
description: "The type of people to search for. This may\nbe\n\n* `\"staff\"` - only include people whose MIS status is\n `\"\"` (empty string), `\"staff\"`, or\n `\"staff,student\"`.\n\n* `\"student\"` - only include people whose MIS status is set to\n `\"student\"` or `\"staff,student\"`.\n\nOtherwise all matching people will be included (the default). Note\nthat the `\"staff\"` and `\"student\"` options are not\nmutually exclusive."
required: false
schema:
type: string
- name: attributes
in: query
description: 'A comma-separated list of attributes to
consider when searching. If this is `null` (the default) then
all attribute schemes marked as searchable will be included. This is
ignored for LQL queries.'
required: false
schema:
type: string
responses:
200:
description: The number of matching people.
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
value:
type: integer
format: int32
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/person/{scheme}/{identifier}:
get:
tags:
- person
summary: Get the person with the specified identifier.
description: 'Get the person with the specified identifier.
By default, only a few basic details about the person are returned,
but the optional `fetch` parameter may be used to fetch
additional attributes or references of the person.
NOTE: The person returned may be a cancelled person. It is the
caller''s repsonsibility to check its cancelled flag.'
operationId: Person_getPerson
parameters:
- name: scheme
in: path
description: 'The person identifier scheme. Typically this
should be `"crsid"`, but other identifier schemes
such as `"usn"` or `"staffNumber"` may be available.'
required: true
schema:
type: string
- name: identifier
in: path
description: 'The identifier of the person to fetch
(typically their CRSid).'
required: true
schema:
type: string
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch.'
required: false
schema:
type: string
responses:
200:
description: The requested person or `null` if they were not found.
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
person:
$ref: '#/components/schemas/Person'
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/person/{scheme}/{identifier}/get-attributes:
get:
tags:
- person
summary: Get one or more (possibly multi-valued) attributes of a person.
description: 'Get one or more (possibly multi-valued) attributes of a person. The
returned attributes are sorted by attribute scheme precedence and
then attribute precedence.'
operationId: Person_getAttributes
parameters:
- name: scheme
in: path
description: 'The person identifier scheme. Typically this
should be `"crsid"`, but other identifier schemes may be
available in the future, such as `"usn"` or
`"staffNumber"`.'
required: true
schema:
type: string
- name: identifier
in: path
description: 'The identifier of the person (typically
their CRSid).'
required: true
schema:
type: string
- name: attrs
in: query
description: 'The attribute scheme(s) to fetch. This may
include any number of the attributes or pseudo-attributes, but it
may not include references or attribute chains (see the documentation
for the `fetch` parameter in this class).'
required: true
schema:
type: string
responses:
200:
description: The requested attributes.
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
attributes:
type: array
items:
$ref: '#/components/schemas/Attribute'
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/person/{scheme}/{identifier}/groups:
get:
tags:
- person
summary: 'Get all the groups to which the specified person belongs, including
indirect group memberships, via groups that include other groups.'
description: 'Get all the groups to which the specified person belongs, including
indirect group memberships, via groups that include other groups.
The returned list of groups is sorted by groupid.
Note that some group memberships may not be visible to you. This
method will only return those group memberships that you have
permission to see.
By default, only a few basic details about each group are returned,
but the optional `fetch` parameter may be used to fetch
additional attributes or references of each group.
NOTE: This method will not include cancelled groups.'
operationId: Person_getGroups
parameters:
- name: scheme
in: path
description: 'The person identifier scheme. Typically this
should be `"crsid"`, but other identifier schemes may be
available in the future, such as `"usn"` or
`"staffNumber"`.'
required: true
schema:
type: string
- name: identifier
in: path
description: 'The identifier of the person (typically
their CRSid).'
required: true
schema:
type: string
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch.'
required: false
schema:
type: string
responses:
200:
description: The person's groups (in groupid order).
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
groups:
type: array
items:
$ref: '#/components/schemas/Group'
description: 'Class representing the top-level container for all XML and JSON results.
This may be just a simple textual value or it may contain more complex
entities such as people, institutions, groups, attributes, etc.'
default:
$ref: '#/components/responses/ServerError'
/person/{scheme}/{identifier}/insts:
get:
tags:
- person
summary: Get all the institutions to which the specified person belongs.
description: 'Get all the institutions to which the specified person belongs. The
returned list of institutions is sorted by name.
By default, only a few basic details about each institution are
returned, but the optional `fetch` parameter may be used
to fetch additional attributes or references of each institution.
NOTE: This method will not include cancelled institutions.'
operationId: Person_getInsts
parameters:
- name: scheme
in: path
description: 'The person identifier scheme. Typically this
should be `"crsid"`, but other identifier schemes may be
available in the future, such as `"usn"` or
`"staffNumber"`.'
required: true
schema:
type: string
- name: identifier
in: path
description: 'The identifier of the person (typically
their CRSid).'
required: true
schema:
type: string
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch.'
required: false
schema:
type: string
responses:
200:
description: The per
# --- truncated at 32 KB (63 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/university-of-cambridge/refs/heads/main/openapi/university-of-cambridge-person-api-openapi.yml