openapi: 3.0.0
info:
title: Lookup/Ibis web service group institution 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: institution
description: "Methods for querying and manipulating institutions.\n\n#### The fetch parameter for institutions\n\nAll methods that return institutions also accept an optional\n`fetch` parameter that may be used to request additional\ninformation about the institutions returned. For more details about\nthe general rules that apply to the `fetch` parameter,\nrefer to the `PersonMethods` documentation.\n\nFor institutions the `fetch` parameter may be used to fetch\nany institution attribute by specifying the `schemeid` of an\ninstitution attribute scheme. Examples include `\"address\"`,\n`\"jpegPhoto\"`, `\"universityPhone\"`, `\"instPhone\"`,\n`\"landlinePhone\"`, `\"mobilePhone\"`, `\"faxNumber\"`,\n`\"email\"` and `\"labeledURI\"`. The full list (which may be\nextended over time) may be obtained using `#allAttributeSchemes`.\n\nIn addition the following pseudo-attributes are supported:\n\n* `\"phone_numbers\"` - fetches all phone numbers. This is\n equivalent to\n `\"universityPhone,instPhone,landlinePhone,mobilePhone\"`.\n\n* `\"all_attrs\"` - fetches all attributes from all institution\n attribute schemes. This does not include references.\n\n* `\"contact_rows\"` - fetches all institution contact rows. Any\n chained fetches from contact rows are used to fetch attributes from any\n people referred to by the contact rows.\n\nThe `fetch` parameter may also be used to fetch referenced\npeople, institutions or groups. This will only include references to\nnon-cancelled entities. The following references are supported:\n\n* `\"all_members\"` - fetches all the people who are members of the\n institution.\n\n* `\"parent_insts\"` - fetches all the parent institutions. Note\n that currently all institutions have only one parent, but this may change\n in the future, and client applications should be prepared to handle\n multiple parents.\n\n* `\"child_insts\"` - fetches all the child institutions.\n\n* `\"inst_groups\"` - fetches all the groups that belong to the\n institution.\n\n* `\"members_groups\"` - fetches all the groups that form the\n institution's membership list.\n\n* `\"managed_by_groups\"` - fetches all the groups that manage the\n institution's data (commonly called \"Editor\" groups).\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 institution. For more information about what can be fetched from\nreferenced people and groups, refer to the documentation for\n`PersonMethods` and `GroupMethods`."
paths:
/inst/all-attr-schemes:
get:
tags:
- institution
summary: Return a list of all the institution attribute schemes available.
description: 'Return a list of all the institution attribute schemes available.
The `schemeid` values of these schemes may be used in the
`fetch` parameter of other methods that return institutions.'
operationId: Institution_allAttributeSchemes
responses:
200:
description: 'All the available institution 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'
/inst/all-insts:
get:
tags:
- institution
summary: Return a list of all institutions.
description: 'Return a list of all institutions.
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.'
operationId: Institution_allInsts
parameters:
- name: includeCancelled
in: query
description: 'Whether or not to include cancelled
institutions. By default, only live institutions are returned.'
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 requested institutions (in instid order).
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
institutions:
type: array
items:
$ref: '#/components/schemas/Institution'
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'
/inst/list:
get:
tags:
- institution
summary: Get the institutions with the specified IDs.
description: 'Get the institutions with the specified IDs.
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.
The results are sorted by ID.
NOTE: The URL path length is limited to around 8000 characters, and
an instid is up to 8 characters long. Allowing for comma separators
and URL encoding, this limits the number of institutions that this
method may fetch to around 700.
NOTE: The institutions returned may include cancelled institutions.
It is the caller''s responsibility to check their cancelled flags.'
operationId: Institution_listInsts
parameters:
- name: instids
in: query
description: A comma-separated list of instids.
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 institutions (in instid order).
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
institutions:
type: array
items:
$ref: '#/components/schemas/Institution'
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'
/inst/modified-insts:
get:
tags:
- institution
summary: 'Find all institutions modified between the specified pair of
transactions.'
description: 'Find all institutions 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) institutions were affected.
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.
NOTE: All data returned reflects the latest available data about each
institution. It is not possible to query for old data, or more
detailed information about the specific changes made.'
operationId: Institution_modifiedInsts
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: instids
in: query
description: 'Only include institutions with instids in
this list. By default, all modified institutions will be included.'
required: false
schema:
type: string
- name: includeCancelled
in: query
description: 'Include cancelled institutions. By
default, cancelled institutions are excluded.'
required: false
schema:
type: boolean
- name: contactRowChanges
in: query
description: 'Include institutions whose contact
rows have changed. By default, changes to institution contact rows are
not taken into consideration.'
required: false
schema:
type: boolean
- name: membershipChanges
in: query
description: 'Include institutions whose members
have changed. By default, changes to institutional memberships are not
taken into consideration.'
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 institutions (in instid order).
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
institutions:
type: array
items:
$ref: '#/components/schemas/Institution'
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'
/inst/search:
get:
tags:
- institution
summary: Search for institutions using a free text query string.
description: 'Search for institutions 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 institution 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 `"inst:"`, 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 value of `includeCancelled`. In
addition, an LQL query will ignore the `orderBy` parameter,
since LQL queries always return results in ID order.'
operationId: Institution_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 institutions
to be included. Defaults to `false`.'
required: false
schema:
type: boolean
- 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 `"instid"` or `"name"` (the default for
non-LQL queries). This is ignored for LQL queries, which always return
results in instid 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 institutions.
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
institutions:
type: array
items:
$ref: '#/components/schemas/Institution'
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'
/inst/search-count:
get:
tags:
- institution
summary: 'Count the number of institutions that would be returned by a search
using a free text query string.'
description: 'Count the number of institutions that would be returned by a search
using a free text query string.
NOTE: If the query string starts with the prefix `"inst:"`, 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 value of `includeCancelled`.'
operationId: Institution_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 institutions
to be included. Defaults to `false`.'
required: false
schema:
type: boolean
- 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 institutions.
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'
/inst/{instid}:
get:
tags:
- institution
summary: Get the institution with the specified ID.
description: 'Get the institution with the specified ID.
By default, only a few basic details about the institution are
returned, but the optional `fetch` parameter may be used
to fetch additional attributes or references of the institution.
NOTE: The institution returned may be a cancelled institution. It is
the caller''s responsibility to check its cancelled flag.'
operationId: Institution_getInst
parameters:
- name: instid
in: path
description: The ID of the institution to fetch.
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 institution or `null` if it was not found.
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
institution:
$ref: '#/components/schemas/Institution'
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'
/inst/{instid}/cancelled-members:
get:
tags:
- institution
summary: Get all the cancelled members of the specified institution.
description: 'Get all the cancelled members of the specified institution.
By default, only a few basic details about each member are returned,
but the optional `fetch` parameter may be used to fetch
additional attributes or references of each person.
NOTE: This method returns only cancelled people. It does not include
people who were removed from the institution. Cancelled people are no
longer considered to be current staff, students or accredited visitors,
and are no longer regarded as belonging to any groups or institutions.
The list returned here reflects their institutional memberships just
before they were cancelled, and so is out-of-date data that should be
used with caution.'
operationId: Institution_getCancelledMembers
parameters:
- name: instid
in: path
description: The ID of the institution.
required: true
schema:
type: string
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch for each person.'
required: false
schema:
type: string
responses:
200:
description: The institution's cancelled members (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'
/inst/{instid}/contact-rows:
get:
tags:
- institution
summary: Get all the contact rows of the specified institution.
description: 'Get all the contact rows of the specified institution.
Any addresses, email addresses, phone numbers and web pages
associated with the contact rows are automatically returned, as
well as any people referred to by the contact rows.
If any of the contact rows refer to people, then only a few basic
details about each person are returned, but the optional
`fetch` parameter may be used to fetch additional
attributes or references of each person.
NOTE: This method will not include cancelled people.'
operationId: Institution_getContactRows
parameters:
- name: instid
in: path
description: The ID of the institution.
required: true
schema:
type: string
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch for any people referred to by any
of the contact rows.'
required: false
schema:
type: string
responses:
200:
description: The institution's contact rows.
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
institution.contactRows:
type: array
items:
$ref: '#/components/schemas/ContactRow'
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'
/inst/{instid}/get-attributes:
get:
tags:
- institution
summary: Get one or more (possibly multi-valued) attributes of an institution.
description: 'Get one or more (possibly multi-valued) attributes of an institution.
The returned attributes are sorted by attribute scheme precedence and
then attribute precedence.'
operationId: Institution_getAttributes
parameters:
- name: instid
in: path
description: The ID of the institution.
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'
/inst/{instid}/members:
get:
tags:
- institution
summary: Get all the members of the specified institution.
description: 'Get all the members of the specified institution.
By default, only a few basic details about each member are returned,
but the optional `fetch` parameter may be used to fetch
additional attributes or references of each person.
NOTE: This method will not include cancelled people.'
operationId: Institution_getMembers
parameters:
- name: instid
in: path
description: The ID of the institution.
required: true
schema:
type: string
- name: fetch
in: query
description: 'A comma-separated list of any additional
attributes or references to fetch for each person.'
required: false
schema:
type: string
responses:
200:
description: The institution's members (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'
/inst/{instid}/{attrid}:
get:
tags:
- institution
summary: Get a specific attribute of an institution.
description: Get a specific attribute of an institution.
operationId: Institution_getAttribute
parameters:
- name: instid
in: path
description: The ID of the institution.
required: true
schema:
type: string
- name: attrid
in: path
description: The ID of the attribute to fetch.
required: true
schema:
type: integer
format: int64
responses:
200:
description: The requested attribute.
content:
application/json:
schema:
type: object
properties:
result:
type: object
properties:
attribute:
$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'
components:
schemas:
Identifier:
type: object
properties:
scheme:
type: string
description: The identifier's scheme (e.g., "crsid").
value:
type: string
description: The identifier's value in that scheme (e.g., a specific CRSid value).
description: Class representing a person's identifier, for use by the web service API.
ContactRow:
type: object
properties:
description:
type: string
description: The contact row's text.
bold:
type: boolean
description: 'Flag indicating if the contact row''s text is normally displayed in
bold.'
italic:
type: boolean
description: 'Flag indicating if the contact row''s text is normally displayed in
italics.'
addresses:
type: array
items:
type: string
description: 'A list of the contact row''s addresses. This will always be non-null,
but may be an empty list.'
emails:
type: array
items:
type: string
description: 'A list of the
# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/university-of-cambridge/refs/heads/main/openapi/university-of-cambridge-institution-api-openapi.yml