Accessing user information

:: services/users module

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).

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.

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.

Returned value:

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..

Returned value:

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.

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.

Returned value:

Returned value:

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

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).

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).

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.)

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.

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"}}