Accessing user information
:: services/users module

These methods allow you to search for USOS users and access information on their profiles.

Some examples of usage:

  • You may use it to authenticate users on your website. If you designed a website which is specifically intended to use by a subset of users in your university, then USOS API gives you an easy way to confirm who users are.
  • You could design a local search box, to be placed on web pages of individual faculties, and which would allow visitors to search among staff members of this faculty. Note, that this doesn't require any server-side code, client-side AJAX is all you need (as long as you search among staff members only).

Methods

change BETA Change user data.
employment_functions Get information on employment functions of a given user.
employment_group Get information on employment group
employment_groups_index Get information on employment group
employment_positions Get information on employment positions of a given user.
pesel Get information on a user given by PESEL number. (administrative)
photo (deprecated) Get user's photo.
position Description of employee position
search (deprecated) Search among all users.
search2 Search for users.
search_by_email Search for users with a given email address. (administrative)
search_current_students (deprecated) Search among current students.
search_current_teachers (deprecated) Search among current teachers.
search_history_affect Add a user to search history.
search_staff (deprecated) Search among all staff members.
search_students (deprecated) Search among all students.
staff_index Retrieve lists of faculty staff members.
student_index Retrieve lists of students.
student_programmes (deprecated) Get information on user's studies.
user Get information on a given user.
user2 Get information on a given user.
users Get information on multiple users.

services/users/change

Consumer: required Token: optional Scopes: n/a SSL: required
https://usosapps.demo.usos.edu.pl/services/users/change

This is a BETA method. We're looking for beta-testers. Until we find them, there's a substantial probability it won't stay backwards-compatible! If you are planning on using this method, please let us know. Then, we will work with you and move it out of beta as soon as we can.

Change user data, such as his email address, or phone number.

The number of fields which you can change with this method is very limited, but it will grow depending on users' needs (contact us if you want more fields supported).

All the changes made by this method are atomic. That is, if any of the changes fail to be saved, then none of them will be saved.

Please note that it may take time for some changes to propagate to all USOS-related applications.

user_id optional

Default value: (empty string)

The ID of the user whose data is to be updated. Required if you don't use an Access Token.

email optional

Default value: (unchanged)

If given, then user's email address will be replaced with the given value.

Administrative Consumer Key required.

alt_email optional

Default value: (unchanged)

If given, then user's alternative email address will be replaced with the given value.

Scope required: edit_user_attrs.

homepage_url optional

Default value: (unchanged)

If given, then user's homepage URL will be replaced with the given value.

Administrative Consumer Key required.

phone_numbers optional

Default value: (unchanged)

Pipe-separated list of strings. If given, then user's official phone numbers will be replaced with the given values. Note, that currently only staff members are allowed to have phone numbers, and no more than two of them. This may change in future.

Administrative Consumer Key required.

mobile_numbers optional

Default value: (unchanged)

Pipe-separated list of strings. If given, then user's mobile phone numbers will be replaced with the given values. This may change in future.

Administrative Consumer Key required.

room_id optional

Default value: (unchanged)

ID of a room. If given, then the user's current office room will be replaced with the given one. Note, that only staff members are allowed to have an office room.

Administrative Consumer Key required.

revenue_office_id optional

Default value: (unchanged)

ID of revenue office. If given, then user's revenue office ID will be replaced with the given one.

Administrative Consumer Key required.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

If all changes succeed, {"success": true} will be returned.

If any of the changes fail, then none of them will be saved, and you will receive HTTP 400 error with detailed error message. This error message is given in plaintext string - readable to humans, but not to machines. Contact us if you need enhanced error handling in your application (e.g. error codes, or list of invalid fields).

The error response may (but doesn't have to) contain the user_messages field (especially if you're changing the fields editable by non-administrative consumers).

services/users/employment_functions

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapps.demo.usos.edu.pl/services/users/employment_functions

This method returns similar results as the employment_functions field of the user method, but it may return past employments too (provided you have proper access).

user_id optional

Default value: (access token issuer)

ID of a user.

fields optional

Default value: function|faculty

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

include_past optional

Default value: auto

One of the following values:

  • false - only current employments will be returned.
  • true - try to return both current, and past employments. Currently only administrative requests and the user himself can access his past employments. If you don't have proper permissions, then only the current employments will be returned.
  • auto - for backward compatibility, you should avoid using this; if auto if provided, then the value of include_past will be determined automatically with the following algorithm:

    If an Access Token is given and the issuer of this token equals to user_id then true.

    If method is called with an Administrative Request then true.

    Else - false.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

A list of dictionaries. Each dictionary contains following fields:

  • function - LangDict object with the name of a employment function;

  • faculty - faculty (id and name fields only) related to the user and this function;

  • is_official - boolean, true if the function is "official".

    Official functions can be promoted, e.g. displayed next to the user's name. Unofficial functions usually should not be displayed, as they are often internal, and would be vague for most viewers.

Thrown errors:

  • object_not_found - some of the referenced objects do not exist; param_name is equal to user_id.

services/users/employment_group

Consumer: ignored Token: ignored Scopes: n/a SSL: required
https://usosapps.demo.usos.edu.pl/services/users/employment_group

Get information on employment group

id required ID of a group
fields optional

Default value: id|name|university_teachers

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • id - ID of a group;

  • name - Langdict object - name of a group;

  • university_teachers - Boolean - true if this is group of teachers.

services/users/employment_groups_index

Consumer: ignored Token: ignored Scopes: n/a SSL: required
https://usosapps.demo.usos.edu.pl/services/users/employment_groups_index

Get information on employment group

fields optional

Default value: id|name|university_teachers

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of employment_group method.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

List of all existing employment groups, as defined in employment_group.

services/users/employment_positions

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapps.demo.usos.edu.pl/services/users/employment_positions

Get information on employment positions of a given user. Only the current positions will be returned.

user_id optional

Default value: (access token issuer)

ID of a user.

include_past optional

Default value: false

By default past employments are omnited. To disable this behaviout setset parameter to true. Note that only administrative consumersare allowed to do this.
fields optional

Default value: position|faculty

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • position - Employee's position.

    This field references objects returned by position method. See its returns section for possible subfields.

  • faculty - A dictionary with the id and name (LangDict) of the faculty..

Thrown errors:

  • object_not_found - some of the referenced objects do not exist; param_name is equal to user_id.

services/users/pesel

Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: not required
https://usosapps.demo.usos.edu.pl/services/users/pesel

Get information on a user given by PESEL number.

pesel required

Pesel number. Must be an exact match.

fields optional

Default value: id|first_name|last_name

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of user method.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required.

Returned value:

A dictionary that contains a user description, as defined in the user method.

Thrown errors:

  • object_not_found - some of the referenced objects do not exist; param_name is equal to pesel.

services/users/photo

Consumer: required Token: required Scopes: photo SSL: not required
https://usosapps.demo.usos.edu.pl/services/users/photo

This method is deprecated, please avoid using it - read more

Get user's photo.

This method is deprecated. Please use the photo_urls field of the user method.

(this method takes no parameters)
Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

Returned value:

Photo of the user who authorized the Access Token.

  • If everything is OK, you will receive binary stream in a JPEG format.
  • If something is wrong (i.e. user has no photo), you will get a HTTP 400 error message.

    Note, that you may also check if the photo exists, with has_photo field of the user method.

Thrown errors:

  • object_not_found - this user does not have a photo.

services/users/position

Consumer: ignored Token: ignored Scopes: n/a SSL: required
https://usosapps.demo.usos.edu.pl/services/users/position

Description of employee position

id required ID of a position
fields optional

Default value: id|name

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

No additional OAuth arguments are required. If you provide any, they will be ignored.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • id - ID of a position;

  • name - name of a position;

  • employment_group - Employment group that position belongs to.

    This field references objects returned by employment_group method. See its returns section for possible subfields.

Consumer: required Token: optional Scopes: n/a SSL: not required
https://usosapps.demo.usos.edu.pl/services/users/search

This method is deprecated, please avoid using it - read more

Suggested replacement: services/users/search2

Why deprecated? Because you can get more features and - in some cases - achieve better performance by using the search2 method.

Search for users matching given query. All users are taken into consideration (students, ex-students, staff, etc.). If you'd like to limit your search - use one of the other methods.

name optional

Default value: (empty string)

The search query. The most obvious value for this field is the user's name, but we'll try to be smart about it (for example, it allows you to find a student by his/her student number, etc.).

num optional

Default value: 6

The number of search results to return. The maximum allowed value of num is 20.

start optional

Default value: 0

Indicates the first matching search result that should be included in the response. This parameter uses a zero-based index, meaning the first result is 0, the second result is 1 and so forth.

Note, that no more than 100 search result will ever be returned for any query, even if more than 100 matches were found. If you need more, than probably you're looking at a wrong method. Contact us if you're not sure.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

A dictionary of following fields and their values:

  • items - a list of matching users. The length of this list is limited to num items. You can access further results by specifing the start argument.

    Each item on this list is a dictionary of the following structure:
    • user_id - ID of a user,
    • match - user's name, with matching fragments highlighted with HTML <b> tag. For example, is you searched for "kowal", then match might be "Jan <b>Kowal</b>ski",

    • active_student_programmes - only active student's programmes, same format as in the services/progs/student method,
    • active_employment_functions - only active employment functions, same format as in the employment_functions method.
  • next_page - boolean, indicates if there is a next page of results for this query.

services/users/search2

Consumer: required Token: optional Scopes: n/a SSL: not required
https://usosapps.demo.usos.edu.pl/services/users/search2

Search for users matching the given query and/or filters.

By default, this method will search among all users (ex- students, past staff members, etc.). If you'd like to search only in a limited subset of users, then try using some of the optional parameters.

Please note, that other USOS API modules may expose their own, specialized user-searching methods. For example, if you want to search only among such users which are related to a given exam, then you should first try looking for an appropriate method in the exams module, not here. (However, such specialized methods are sparse, and probably you'll end up using this one anyway.)

USOS API supports personalized search results. For example, it may display certain items higher in the results, based on personal user preferences and connections. You should include Access Tokens in your requests in order to make use of these features. For best results, you should also use the search_history_affect method.

lang required

A code of the preferred language ("pl" or "en"). It may influence the order and other properties of the returned matches (in particular, the language used in the match field).

fields optional

Default value: items|next_page

Or, more precisely: items[user[id]|match]|next_page

A selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

query optional

Default value: (empty string)

The search query. The most obvious value for this field is the user's name, but we'll try to be smart about it. For example, we may choose to find a student by his/her student number, or email address etc. Also, even more similar features may be added in time. However, these extra searching features are currently not documented and are not guaranteed to work in the future.

among optional

Default value: all

Pipe-separated list of "primary user classes" among which to search. If you provide more than one then the results will include users which fall into at least one of the given classes. (So, this method allows you to "OR" these conditions, but not "AND" them.)

Allowed class codes include:

  • all - all the users;
  • students - users which are - or once have been - students. This includes ex-students and graduates;
  • current_students - users which currently are students. A "current student" is one that is currently studying in at at least one study programme;
  • staff - users which are - or once have been - staff members. This includes all staff members in the USOS database, employed presently or in the past,
  • current_staff - users which currently are staff members. This does not include staff members employed in the past,
  • current_teachers - staff members which are currently teaching.
num optional

Default value: 6

The number of search results to return. The maximum allowed value of num is 20.

start optional

Default value: 0

Zero-based offset of the first item that should be included in the response. (Or, in other words, the number of items to strip from the beginning of the items-list.)

Note, that no more than 100 items can ever be returned for any query, even if more than 100 matches were found. If you need more, than probably you're looking at a wrong method. Contact us if you're not sure.

format optional

Default value: json

Format in which to return values. See supported output formats.

callback optional

Required only if you've chosen jsonp as a return format.

Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • items - a list of items which have matched your query.

    The length of this list is limited to num items. You can access further results by specifying the start argument.

    Each item on this list is a dictionary of the following structure (you can choose more fields with a subfield selector):

    • user - a user object, as described in the user method.
    • match - user's name, with matching fragments highlighted with HTML <b> tag. For example, is you searched for "kowal", then match might be "Jan <b>Kowal</b>ski".

      Please note, that the match may contain other data except the user's name! For example, if you provide a student number in your query, then the match may also include this student number, etc.

  • next_page - boolean, indicates if there is a next page of results for this query.

  • services/users/search_by_email

    Administrative: This method requires a proper Administrative Consumer Key. Contact us to get one.

    Consumer: required (administrative) Token: ignored Scopes: n/a SSL: not required
    https://usosapps.demo.usos.edu.pl/services/users/search_by_email

    Search for users with a given email address.

    • We do not guarantee the uniqueness of users' emails. Therefore, there might actually be more than one result for your query.
    • We store only one email address per user. Some users use aliases (alternate names for their email accounts), this method won't help you identify users of such aliases.
    email required

    Email address. Must be an exact match (case insensitive).

    fields optional

    Default value: id|first_name|last_name

    Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of user method.

    format optional

    Default value: json

    Format in which to return values. See supported output formats.

    callback optional

    Required only if you've chosen jsonp as a return format.

    Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Token is not required.

    Returned value:

    List of dictionaries. Each dictionary contains a user description, as defined in the user method.

    services/users/search_current_students

    Consumer: required Token: optional Scopes: n/a SSL: not required
    https://usosapps.demo.usos.edu.pl/services/users/search_current_students

    This method is deprecated, please avoid using it - read more

    Why deprecated? Because you can get more features and - in some cases - achieve better performance by using the search2 method.

    Search for current students matching given query. A "current student" is one that is currently studying at at least one study programme.

    name optional

    Default value: (empty string)

    The search query. The most obvious value for this field is the user's name, but we'll try to be smart about it (for example, it allows you to find a student by his/her student number, etc.).

    num optional

    Default value: 6

    The number of search results to return. The maximum allowed value of num is 20.

    start optional

    Default value: 0

    Indicates the first matching search result that should be included in the response. This parameter uses a zero-based index, meaning the first result is 0, the second result is 1 and so forth.

    Note, that no more than 100 search result will ever be returned for any query, even if more than 100 matches were found. If you need more, than probably you're looking at a wrong method. Contact us if you're not sure.

    format optional

    Default value: json

    Format in which to return values. See supported output formats.

    callback optional

    Required only if you've chosen jsonp as a return format.

    Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

    Returned value:

    Same format as in the search method.

    services/users/search_current_teachers

    Consumer: optional Token: optional Scopes: n/a SSL: not required
    https://usosapps.demo.usos.edu.pl/services/users/search_current_teachers

    This method is deprecated, please avoid using it - read more

    Why deprecated? Because you can get more features and - in some cases - achieve better performance by using the search2 method.

    Same as search_staff method, but includes only these staff members which are currently teaching.

    name optional

    Default value: (empty string)

    The search query. The most obvious value for this field is the user's name, but we'll try to be smart about it (for example, it allows you to find a student by his/her student number, etc.).

    num optional

    Default value: 6

    The number of search results to return. The maximum allowed value of num is 20.

    start optional

    Default value: 0

    Indicates the first matching search result that should be included in the response. This parameter uses a zero-based index, meaning the first result is 0, the second result is 1 and so forth.

    Note, that no more than 100 search result will ever be returned for any query, even if more than 100 matches were found. If you need more, than probably you're looking at a wrong method. Contact us if you're not sure.

    format optional

    Default value: json

    Format in which to return values. See supported output formats.

    callback optional

    Required only if you've chosen jsonp as a return format.

    Plus optional standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

    Returned value:

    Same format as in the search method.

    services/users/search_history_affect

    Consumer: required Token: required Scopes: none SSL: not required
    https://usosapps.demo.usos.edu.pl/services/users/search_history_affect

    Add a user to search history.

    This method aims on improving user experience while searching. Call this method once your user visits another user's page, or when he/she selects a given user while searching for users, etc.

    The selected user will be added to search history (currently stored separately for each consumer key and each user). Items saved in search history may appear more frequently in future search results, etc.

    user_id required

    The ID of the user to be saved into the search history.

    format optional

    Default value: json

    Format in which to return values. See supported output formats.

    callback optional

    Required only if you've chosen jsonp as a return format.

    Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

    Returned value:

    Currently, it always returns {"success": true}.

    services/users/search_staff

    Consumer: required Token: optional Scopes: n/a SSL: not required
    https://usosapps.demo.usos.edu.pl/services/users/search_staff

    This method is deprecated, please avoid using it - read more

    Why deprecated? Because you can get more features and - in some cases - achieve better performance by using the search2 method.

    Search for staff members matching given query. This is very similar to the search method, but searches among staff members only. This includes all staff members in the USOS database, employed presently and in the past. This is usually less interesting than, for example, the search_current_teachers method.

    name optional

    Default value: (empty string)

    The search query. The most obvious value for this field is the user's name, but we'll try to be smart about it (for example, it allows you to find a student by his/her student number, etc.).

    num optional

    Default value: 6

    The number of search results to return. The maximum allowed value of num is 20.

    start optional

    Default value: 0

    Indicates the first matching search result that should be included in the response. This parameter uses a zero-based index, meaning the first result is 0, the second result is 1 and so forth.

    Note, that no more than 100 search result will ever be returned for any query, even if more than 100 matches were found. If you need more, than probably you're looking at a wrong method. Contact us if you're not sure.

    format optional

    Default value: json

    Format in which to return values. See supported output formats.

    callback optional

    Required only if you've chosen jsonp as a return format.

    Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

    Returned value:

    Same format as in the search method.

    services/users/search_students

    Consumer: required Token: optional Scopes: n/a SSL: not required
    https://usosapps.demo.usos.edu.pl/services/users/search_students

    This method is deprecated, please avoid using it - read more

    Why deprecated? Because you can get more features and - in some cases - achieve better performance by using the search2 method.

    Search for students matching given query. This includes also ex-students/graduates. If you want to search among current students, use the search_current_students method.

    name optional

    Default value: (empty string)

    The search query. The most obvious value for this field is the user's name, but we'll try to be smart about it (for example, it allows you to find a student by his/her student number, etc.).

    num optional

    Default value: 6

    The number of search results to return. The maximum allowed value of num is 20.

    start optional

    Default value: 0

    Indicates the first matching search result that should be included in the response. This parameter uses a zero-based index, meaning the first result is 0, the second result is 1 and so forth.

    Note, that no more than 100 search result will ever be returned for any query, even if more than 100 matches were found. If you need more, than probably you're looking at a wrong method. Contact us if you're not sure.

    format optional

    Default value: json

    Format in which to return values. See supported output formats.

    callback optional

    Required only if you've chosen jsonp as a return format.

    Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

    Returned value:

    Same format as in the search method.

    services/users/staff_index

    Consumer: required Token: optional Scopes: n/a SSL: not required
    https://usosapps.demo.usos.edu.pl/services/users/staff_index

    Retrieve lists of staff members of the given faculty.

    This is different than searching. The search2 method aims at simplifing the task of finding one particular user, whereas the *_index methods are designed to return ordered lists of users matching the given, simple criteria. In this case, it returns all the staff members of the given faculty.

    You might say, that search methods are for humans, and index methods are for automated robots (e.g. for pages to by crawled by Google), but that's not always the case.

    Note that there is no limit on the number of items returned via the index method. Still, you cannot retrieve all items in a single request - you need to paginate your results.

    The results of this method may vary on the permissions of your user.

    fac_ids required

    Pipe-separated list of faculty IDs (usually a single faculty). Staff members of these faculties will be returned.

    teachers_only optional

    Default value: false

    If set to true then the results will be additionally filtered and will contain active academic teachers only.

    fields optional

    Default value: users|next_page|total

    Or, more precisely: users[id|first_name|last_name]|next_page|total

    A selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

    num optional

    Default value: 20

    The maximum number of items to return on one "page". The maximum allowed value of num is 100.

    start optional

    Default value: 0

    Zero-based offset of the first item that should be included in the response. (Or, in other words, the number of items to strip from the beginning of the items-list.)

    format optional

    Default value: json

    Format in which to return values. See supported output formats.

    callback optional

    Required only if you've chosen jsonp as a return format.

    Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

    Returned value:

    A dictionary of selected fields and their values.

    Available fields:

    • users - a list of users which have matched your query.

      The length of this list is limited to num items. You can access further results by specifying the start argument.

      Each item on this list is a dictionary of the structure described in the user method. You may access more fields with a subfield selector).

  • next_page - boolean, indicates if there is a next page of results for this query;

  • total - integer, total number of matched items.

  • services/users/student_index

    Consumer: required Token: optional Scopes: n/a SSL: not required
    https://usosapps.demo.usos.edu.pl/services/users/student_index

    Retrieve lists of students, grouped by various criteria.

    The results of this method may vary on the permissions and roles of your user. If you don't have proper permissions, then empty list of results will be returned (no error will be raised). Currently, all requests with any valid Access Token have access to everything, but this is likely to change in the near future.

    Note that you can use programme_ids or country_id, but not both (they're mutually exclusive)!

    programme_ids optional

    Default value: (empty string)

    Pipe-separated list of programme IDs (usually a single programme). Students of these programmes will be returned.

    country_id optional

    Default value: (empty string)

    If you are an Administrative Consumer, then you can use this method to retrieve all the students which have the nationality of the given country. Supply a single ISO 3166-1 alpha-2 code in this parameter.

    If you have an Access Token, then you can also use the special "mine" value, which will return the students of the same nationality as your user has. This will also work with non-administrative consumers, however the results can be very limited, depending on your scopes and the preferences of your user and other users of the same nationality (some students may agree to share more data than others).

    Important: This parameter is designed for mobility applications and it won't work for the Polish nationality. You will receive an empty response if you supply 'PL', or when your user is Polish.

    fields optional

    Default value: users|next_page|total

    Or, more precisely: users[id|first_name|last_name]|next_page|total

    A selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

    num optional

    Default value: 20

    The maximum number of items to return on one "page". The maximum allowed value of num is 100.

    start optional

    Default value: 0

    Zero-based offset of the first item that should be included in the response. (Or, in other words, the number of items to strip from the beginning of the items-list.)

    format optional

    Default value: json

    Format in which to return values. See supported output formats.

    callback optional

    Required only if you've chosen jsonp as a return format.

    Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

    Returned value:

    A dictionary of selected fields and their values.

    Available fields:

    • users - a list of users which have matched your query.

      The length of this list is limited to num items. You can access further results by specifying the start argument. (The list is ordered by name.)

      Each item on this list is a dictionary of the structure described in the user method. You may access more fields with a subfield selector).

  • next_page - boolean, indicates if there is a next page of results for this query;

  • total - integer, total number of matched items.

  • services/users/student_programmes

    Consumer: required Token: required Scopes: studies SSL: not required
    https://usosapps.demo.usos.edu.pl/services/users/student_programmes

    This method is deprecated, please avoid using it - read more

    Suggested replacement: services/progs/student

    Get information on user's studies.

    format optional

    Default value: json

    Format in which to return values. See supported output formats.

    callback optional

    Required only if you've chosen jsonp as a return format.

    Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus required oauth_token for Token authorization.

    Returned value:

    A list of dictionaries. Each dictionary contains following fields:

    • id - ID of a programme;

    • name - a LangDict object with the name of a programme.

    services/users/user

    Consumer: required Token: optional Scopes: n/a SSL: not required
    https://usosapps.demo.usos.edu.pl/services/users/user

    Get information on a given user.

    user_id optional

    Default value: (access token issuer)

    ID of a user.

    fields optional

    Default value: id|first_name|last_name

    Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

    format optional

    Default value: json

    Format in which to return values. See supported output formats.

    callback optional

    Required only if you've chosen jsonp as a return format.

    Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

    Returned value:

    A dictionary of selected fields and their values or null if user with given ID does not exist.

    Each dictionary contains following fields:

    • Primary:

      • id - user's ID;

      • first_name - user's first name;

      • middle_names - user's middle name(s), separated with spaces, or null if the user has no middle name(s).

        In most cases, this will be a single name, but not always. See here for the details.

      • last_name - user's last name;

      • previous_names - a list of user's previous names.

        A history of changes to the user's name. Every element is a dictionary with three fields: first_name, last_name and until - a date on which the name was changed. The names are ordered by date, starting with the most recent.

        An empty list indicates that the user has either never changed his/her name, or that he/she had disallowed the name history to be viewed by you (that is, either the issuer of the Access Token, or the Consumer, if you're not using an Access Token).

        Use an Access Token with the personal scope. (Or, acquire Administrative access.)

      • sex - capital M for male, F for female;

      • titles - user's academic titles, to be displayed along his name.

        A dictionary with two fields: before and after. Both fields can be either plain-text string or null. In some contexts it is customary to display these titles before and after the user's name.

      • student_status - integer (0, 1 or 2), or null.

        This indicates the user's status of "being a student". The meaning of the possible values is as follows:

        • null - This means that you are not allowed to access the student status of this user. (You may need to provide an Access Token to access such values.)
        • 0 - The user is not, and never was, a student on any of the study programmes of this university.
        • 1 - The user is an "inactive student". That is, currently he's not studying, but he was an active student in the past.
        • 2 - The user is an active student.

        Please note, that usually you won't have any use for this field. If you are an Administrative Consumer, then you should make your requests via the services/oauth/proxy method - this way, USOS API will do all the heavy lifting regarding data access issues.

      • staff_status - integer (0, 1 or 2).

        This indicates the user's status of "being a staff member". The meaning of the possible values is as follows:

        • 0 - The user is currently not a staff member. He might have been a staff member once, but he is not now.
        • 1 - The user is an employed staff member, but he is not an academic teacher.
        • 2 - The user is an active academic teacher.

        Please note, that usually you won't have any use for this field. If you are an Administrative Consumer, then you should make your requests via the services/oauth/proxy method - this way, USOS API will do all the heavy lifting regarding data access issues.

      • email_access - BETA indicates, if (and how) your user X can access the email address of this user Y.

        Important: This is a BETA field and it is provided primarily for administrative consumers. In most cases, you will want to use the email and email_url fields. You will need the email_access field only if you want to create a custom implementation of the page provided in email_url field.

        Please note, that the fact that user X can access user Y's email, does not mean that you (the Consumer) can. Even if this field returns plaintext, you still may get null in the email field if you don't have the proper scopes!

        If you don't provide an Access Token, then our user X will be an anonymous, external user (such users usually don't see much).

        This field may return any of the following values:

        • no_email - user Y has no email address, therefore nobody can access it.
        • no_access - user Y has an email address, but user X cannot access it.
        • require_captcha - user Y has an email address and user X can access it, but we will first need to make sure that he's not a robot.

          If you're a regular Consumer, then you cannot access such email yourself, but you should point your user to the URL provided in the email_url field. We will verify that user X is not a robot and reveal the email address afterwards.

          If you're an Administrative Consumer, then you can access the email field, but you may not display this email to user X, until you have verified that he's not a robot. You can implement your own captchas, or you can use the email_url field, as regular Consumers do.

        • plaintext - user Y has an email address, and user X is allowed to view it in plaintext. If you have asked for the right scopes, then you should be able to access it via the email field.
      • email - user's email address, or null if it is unknown or you (or your user) don't have access to see it in plaintext.

        You will need the email scope to access the email address of your user (the issuer of your Access Token). You will need the other_emails scope to access email addresses of other users.

        Important: Administrative calls have access to all the emails, regardless of their visibility. You must use the services/oauth/proxy method, or interpret the email_access field properly, before you show this email to your users!

      • email_url - URL of the page with the user's email, or null if the user does not have an email.

        Whenever you cannot access the user's email via the email field, you can display this link instead. We may need to authenticate the user and verify that he's not a robot before we display the email to him.

      • has_email - boolean; true, if we know the user's email address.

        In some cases (e.g. when using the mailing module) it may be desirable for you to know if we actually possess the email address of the user. We won't necessarily share it with you, but we can tell you whether we have it or not.

      • homepage_url - user's homepage URL (or null if none);

      • profile_url - user's usosweb profile URL;

      • phone_numbers - a list of strings (phone numbers).

        Each string is a single contact phone number. These are purely academic-related contact numbers and the list will be always empty for non-academic users.

      • mobile_numbers - a list of strings, or an empty list if don't you have access to view this field.

        Each string is a single mobile phone number. These are personal phone numbers, which can be used e.g. for SMS notifications. You may assume that these numbers are ordered user's by preference. We don't guarantee neither if the number is up-to-date, nor that it is in any commonly recognizable format.

        You will require the mobile_numbers scope in order to access user's mobile numbers. If you don't have it, you will most probably get an empty list here.

      • office_hours - LangDict object with plain text strings.

        This field contains information on the time spans during which a teacher is available to meet with students in his or her office. It may also contain information on holiday plans. It will always be empty for non-staff members. Usually it is short (one sentence), but in some cases it might contain multiple paragraphs of text.
      • interests - LangDict object with plain text strings.

        Currently, this field will always be empty for all non-staff members. Contains a description of the user's fields of interest.
      • has_photo - boolean, indicates if the user has a photo.

        Or, to be more precise, the value of true indicates that the user both has the photo and he/she had allowed the photo to be viewed by you (that is, either the issuer of the Access Token, or the Consumer, if you're not using an Access Token).

        Please note, that currently this field ignores administrative permissions. That is, even if you call this method directly with an Administrative Consumer Key, you may still be denied access to the photo, as any regular Consumer might.

        If you want to get more information as to the reason why you can't see the photo, try using the services/photos/can_see_photo method.

      • photo_urls - A dictionary with user's photo URLs..

        Don't be misled by the plural. Currently, our users have only a single photo each, but it can be delivered in various sizes (hence urls, not url). Use the subfield selector to get the size(s) you need (by default, you will get 50x50).

        Each field contains an URL pointing to an image scaled to different dimensions:

        • 50x50 - 50px x 50px,
        • 100x100 - 100px x 100px,
        • 100x125 - 100px x 125px,
        • 200x200 - 200px x 200px,
        • 200x250 - 200px x 250px,
        • 400x400 - 400px x 400px,
        • 400x500 - 400px x 500px,
        • original - the original size.

        Please note, that we don't require you to have any additional scopes or permissions in order to access this field. You will always find a valid image URL here, but most of those images may be blank (depending on your permissions and scopes).

        Important: The URL is valid only at the time when you are asking for it. You should not cache it. You must ask for this URL every time you want to display it.

        On the other hand, the image which the URL points to, can (and should) be cached according to its Cache-Control and Expires headers. If you're displaying the image in a browser then you don't have to worry about the caching yourself (the browser will cache it for you).

      • student_number - either string, or null.

        If you got a string, then it's the primary student number of this user.

        If it's null, then either the user is not a student, or you don't have access to view his/her student number.

        Note, that you may increase your chances of getting a non-null value by asking your user for the studies and staff_perspective scopes.

      • pesel - either string, or null.

        The PESEL number of the user. If the PESEL number is unknown, or you don't have the access to view it, you will get a null here.

        You must use the Access Token with the personal scope in order to get a non-null value. (Or, acquire Administrative access.)

      • birth_date - either string, or null.

        If birth date is known and you have the necessary permissions to see it, then it will be returned in the "yyyy-mm-dd" format. Otherwise, this will be null.

        You must use the Access Token with the personal scope in order to get a non-null value. (Or, acquire Administrative access.)

      • revenue_office_id - either string, or null.

        If revenue office is not known or you don't have the necessary permissions to see it, you will get null here.

        You must use the Access Token with the personal scope in order to get a non-null value. (Or, acquire Administrative access.)

      • citizenship - object, or null.

        If citizenship is known and you have the necessary permissions to access it, then an object of the following format will be returned:

        • id - an ISO 3166-1 code of the country (these codes are always in upper-case!).

        You must use the Access Token with the personal scope in order to get a non-null value. (Or, acquire Administrative access.)

      • room - the user's office room, or null.

        Note, that only staff members have office rooms (and only some of them).

        This field references objects returned by services/geo/room method. See its returns section for possible subfields (only primary are allowed).

      • student_programmes - student programmes of given user.

        The field will contain student programmes viewable by the issuer of your Access Token. This may include inactive student programmes too. The results may be affected by your access to the studies and/or staff_perspective scopes.

        This field references objects returned by services/progs/student_programme method. See its returns section for possible subfields.

      • employment_functions - current employment functions of given user.

        To access past employments, see employment_functions method. (The format is the same.)

        This field references objects returned by employment_functions method. See its returns section for possible subfields.

      • employment_positions - employment positions of given user.

        This field references objects returned by employment_positions method. See its returns section for possible subfields.

      • course_editions_conducted - BETA a list of active course editions conducted by the user.

        A list of objects that describe course_edition. It differs from services/courses/course_edition object.

        Currently a fixed set of subfields will be returned: id|course[id|name]|term[id|name]. You cannot access other subfields via this method.

      • postal_addresses - a list of personal postal addresses.

        Every item on the list will have the following fields:

        • type - this will be either primary, residence, correspondence, or other. However, clients MUST be prepared that more types of addresses may be used here in the future (e.g. treat them as other).
        • type_name - a LangDict object with a short name of the address type, e.g. "Address of residence".
        • address - string; short, plain-text postal address

        Please note, that you will need as least the personal scope if you want this list to be not empty.

      • alt_email - alternative email address, or null.

        Users are allowed to supply alternative (usually private) email addresses. These addresses are not used in general, and currently they can be accessed only by the user himself (this may change in future).

        You will also need both the email and personal scopes to access this field. If you don't have these permissions you will always get null.

      • can_i_debug - BETA boolean, true if the issuer of your Access Token should be allowed to debug sessions of this user.

        This field is for Administrative Consumers only. There is a number of users which are allowed to debug sessions as other users (in other words, they can sign in to various applications as selected other users). You can use this USOS API method to help you judge if your user should be allowed to do that.

      • external_ids - Dictionary following structure:

        • orcid - User's ORCID idientifier. See orcid.org for more details.
        • pbn_id - User's PBN ID
        ;

      • phd_student_status - integer (0, 1 or 2).

        This indicates the user's status of "being a student of phd programme. The meaning of the possible values is same as student_status.
      • library_card_id - either string, or null.

        The library card ID of the user. If the ID is unknown, or you don't have the access to view it, you will get a null here.

        You must use the Access Token with the personal scope in order to get a non-null value. (Or, acquire Administrative access.)

    Thrown errors:

    • field_forbidden - access to field denied.

      Possible reasons:

      • user_unauthorized - access token issuer does not have permission to retrieve value of this field, because it refers to other user.

    services/users/user2

    Consumer: required Token: optional Scopes: n/a SSL: not required
    https://usosapps.demo.usos.edu.pl/services/users/user2

    Get information on a given user.

    user_id optional

    Default value: (access token issuer)

    ID of a user.

    fields optional

    Default value: id|first_name|last_name

    Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section.

    format optional

    Default value: json

    Format in which to return values. See supported output formats.

    callback optional

    Required only if you've chosen jsonp as a return format.

    Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

    Returned value:

    A dictionary of selected fields and their values.

    Available fields:

    • id - user's ID;

    • first_name - user's first name;

    • student_number - either string, or null.

      If you got a string, then it's the primary student number of this user.

      If it's null, then either the user is not a student, or you don't have access to view his/her student number.

      Note, that you may increase your chances of getting a non-null value by asking your user for the studies and staff_perspective scopes.

    • middle_names - user's middle name(s), separated with spaces, or null if the user has no middle name(s).

      In most cases, this will be a single name, but not always. See here for the details.

    • last_name - user's last name;

    • student_status - integer (0, 1 or 2), or null.

      This indicates the user's status of "being a student". The meaning of the possible values is as follows:

      • null - This means that you are not allowed to access the student status of this user. (You may need to provide an Access Token to access such values.)
      • 0 - The user is not, and never was, a student on any of the study programmes of this university.
      • 1 - The user is an "inactive student". That is, currently he's not studying, but he was an active student in the past.
      • 2 - The user is an active student.

      Please note, that usually you won't have any use for this field. If you are an Administrative Consumer, then you should make your requests via the services/oauth/proxy method - this way, USOS API will do all the heavy lifting regarding data access issues.

    • staff_status - integer (0, 1 or 2).

      This indicates the user's status of "being a staff member". The meaning of the possible values is as follows:

      • 0 - The user is currently not a staff member. He might have been a staff member once, but he is not now.
      • 1 - The user is an employed staff member, but he is not an academic teacher.
      • 2 - The user is an active academic teacher.

      Please note, that usually you won't have any use for this field. If you are an Administrative Consumer, then you should make your requests via the services/oauth/proxy method - this way, USOS API will do all the heavy lifting regarding data access issues.

    Thrown errors:

    • field_forbidden - access to field denied.

      Possible reasons:

      • user_unauthorized - access token issuer does not have permission to retrieve value of this field, because it refers to other user.

    services/users/users

    Consumer: required Token: optional Scopes: n/a SSL: not required
    https://usosapps.demo.usos.edu.pl/services/users/users

    Get information on multiple users.

    This method is similar to the user method, but it works with multiple users.

    user_ids required

    List of user IDs.

    fields optional

    Default value: id|first_name|last_name

    Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of user method.

    format optional

    Default value: json

    Format in which to return values. See supported output formats.

    callback optional

    Required only if you've chosen jsonp as a return format.

    Plus required standard OAuth Consumer signing arguments: oauth_consumer_key, oauth_nonce, oauth_timestamp, oauth_signature, oauth_signature_method, oauth_version. Plus optional oauth_token for Token authorization.

    Returned value:

    A dictionary: your user_ids will be mapped to dictionary's keys, and each value will contain the description of a user, as defined in the user method.

    For example:

    fields=first_name&user_ids=1|2

    might return something like:

    {"1": null, "2": {"first_name": "Wojciech"}}
    USOS API ver. 7.0.2.0-0, 6e2e683c, dirty (2024-03-15)