Housing
:: services/housing module

This is a BETA module. 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 module, please let us know. Then, we will work with you and move it out of beta as soon as we can.

This module allows the users to view and manage their housing-related issues. Currently, only a minor part of all housing-related issues is exposed via USOS API. However, you will still need an introduction to all the related entities and basic workflow in order to use this module properly.

Introduction

During some given periods of time, students may apply for university housing. These periods of time are defined with entities called allocation periods. There is no limit for the number of allocation periods, but usually there will be only one allocation period for every academic term.

In order to apply for university housing the student needs to submit a dorm application. Dorm applications can be either submitted by the students themselves, or be placed directly in the USOS database by a staff member on the basis of a paper application. Students may provide additional information such as their financial situation, distance from their homes to the university or their preferred housing options, e.g. favourite dormitory. All this data is stored in their dorm application.

A selected group of faculties (or other departments, or even other entities) called the trustees review students' applications and award them places in dormitories. Note, that currently there is no identifiable connection between "a trustee" and "a faculty". In other words, currently trustees are just "strings you should display in proper places".

Basic workflow

  • First, the housing staff defines an allocation period. All of the dormitories provide information about their available rooms. It is decided how many of these rooms should be filled during this allocation period (and optionally for students of which specific faculties the places are offered).

    USOS API support: None. Currently, this step is performed directly in the USOS database. There are no methods related to this step in the API.

  • Allocation starts. Students submit their dorm applications.

    USOS API support: None. Currently, this step is performed either directly in the USOS database (by the staff members, based on the paper forms), or by other web applications, unconnected to USOS API. There are no methods related to this step in the API.

  • Allocation finishes. All applications are reviewed (by trustees, described above). Some of the applications are approved, others are rejected.

    Approved applications are also known as assignments. Compared to an application, assignment must contain some additional attributes, such as a specific dormitory ID, room type, move-in & move-out dates, and the number of places allocated (in case of families). All of these attributes are provided by the trustees during the review process.

    USOS API support: None. Currently, this step is performed directly in the USOS database. There are no methods related to this step in the API.

  • A group of users called dormitory administrators manages users' assignments. This includes various tasks, such as, for example, checking the user into a dormitory (which, among other things, includes assigning a specific room for the student when he moves in).

    USOS API support: Yes. Assignment management can be performed via USOS API. Consumers need the dorm_admin scope to act on behalf of dormitory administrators.

Methods

allocation_period BETA Get information on a single allocation period
allocation_period_index BETA Get the index of all allocation periods.
allocation_periods BETA Get information on multiple allocation periods
assignment BETA Get data on a given assignment.
assignment_extend BETA Extend assignment's expiry date.
assignments BETA Get information on multiple assignments.
check_in BETA Check an user into dormitory
check_out BETA Check out a user from a dormitory.
dormitories BETA Get information on multiple dormitories.
dormitory BETA Get information on a single dormitory.
dormitory_index BETA Get the index of all dormitories.
dormitory_user BETA Get information on a given user.
dormitory_users BETA Get information on multiple users.
dormroom BETA Get information on a single dormitory room.
dormroom_type BETA Get information on a single dormroom type
dormroom_type_index BETA Get a list of all dormroom types.
dormroom_types BETA Get information on multiple dormroom types
dormrooms BETA Get information on multiple dormitory rooms.
residence BETA Get information on a single residence
residences BETA Get information on multiple residences.
resident_type BETA Get information on a single resident type
resident_type_index BETA Get a list of all resident types.
resident_types BETA Get information on multiple resident types
unused_assignment_ids BETA Get a list of assignments which were not checked-in yet.

services/housing/allocation_period

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.amu.edu.pl/services/housing/allocation_period

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.

Get information on a single allocation period
allocation_period_id required ID of the allocation period
fields optional

Default value: id

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 this allocation period;

  • term_id - ID of an academic term binded to this allocation period;

  • status_name - LangDict with a short status name of this allocation period;

  • status_desc - LangDict with a longer description of what the status name is about;

  • start_date - datetime string, the start date of the allocation period;

  • end_date - datetime string, the end date of the allocation period.

services/housing/allocation_period_index

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.amu.edu.pl/services/housing/allocation_period_index

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.

Get the index of all allocation periods defined in this USOS installation.
fields optional

Default value: id

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

as_object optional

Default value: false

if true an object is returned instead of a list. The object will be of the same structure as the one returned by the dormroom_types 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:

A list of allocation_period objects, ordered by the start field.

services/housing/allocation_periods

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.amu.edu.pl/services/housing/allocation_periods

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.

Get information on multiple allocation periods
allocation_period_ids required Pipe-separated list of allocation period IDs
fields optional

Default value: id

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of allocation_period 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:

A dictionary: your allocation_period_ids will be mapped to dictionary's keys, and each value will contain an allocation_period object, or null, if no allocation period by given ID was found.

services/housing/assignment

Consumer: required Token: required Scopes: dorm_admin SSL: required
https://usosapps.amu.edu.pl/services/housing/assignment

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.

Get data on a given assignment.

Currently, only dormitory administrators can access assignment data. If your user doesn't have proper permissions, then assignments will appear as nonexistent.

Please note, that assignments are a subset of dorm applications. (Dorm applications are currently not exposed via USOS API, but they're role is explained in the module header.)
assignment_id required ID of the assignment/application
fields optional

Default value: id

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 required oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • id - ID of this assignment;

  • user - the user who is applying for a room in dormitory.

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

  • dormitory - the dormitory applied for.

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

  • resident_type - a resident type the user has been recognised as.

    Note that in case of resident_type requested, but not provided in Assignment model (it is not an obligatory field in USOS), blank result is returned.

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

  • dormroom_type - the room type which the user has been assigned.

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

  • allocation_period - an allocation period during which this assignment was created.

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

  • number_of_places - number of places awarded to the user.

    One person can live at only one dormitory at a time. However, in some cases (e.g. families with children) more than one place can be awarded to one user. In that case, number_of_places field will have a value greater than one.

  • assigned_from - a datetime string; start date of the assignment.

    This indicates the earliest possible date at which the user is allowed to checked in.

  • expiry_date - a datetime string or null, latest date for check-in.

    This indicates the latest possible date at which the user is required to check in.

    Assignments may have an expiry date. If they do, then the user cannot be checked-in after that date passes, and his place may be reassigned to some other user.

  • can_i_extend - boolean; indicates if the requester is allowed to extend the expiry date of this assignment.

    Currently, only dormitory administrators are allowed to extend expiry dates via USOS API.

  • why_cant_i_extend - LangDict or null.

    If the requester is not allowed to extend the expiry date of this assignment, this field will briefly explain why. This is intended to be displayed for the users.

  • assigned_to - a datetime string; end date of the assignment.

    This indicates the latest possible date at which the user is required to check out.

  • trustee_name - a LangDict object.

    Assignments are always awarded by somebody. This field may give a clue on who or what this somebody is.

    Some examples of common values:

    • Department of Physics,
    • International Students Office pool,
    • Rector's pool.

  • residences - list; a history of residence registrations.

    One assignment can be checked-in and checked-out multiple times within the assignment period. The history of these operations is recorded and can be retrieved with this field.

    This field will contain a list of all associated residence objects, ordered by check-in dates.

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

services/housing/assignment_extend

Consumer: required Token: required Scopes: dorm_admin SSL: required
https://usosapps.amu.edu.pl/services/housing/assignment_extend

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.

Extend assignment's expiry date.

Dormitory administrators are allowed to extend expiry dates of assignments which have an expiry date.

If you don't know what expiry date is, please see the expiry_date field in the assignment method.
assignment_id required ID of an unused assignment
new_expiry_date required

Datetime string. New expiry date.
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:

Returns {"success": true} on success. Raises HTTP 400 (with user_messages) on failure.

services/housing/assignments

Consumer: required Token: required Scopes: dorm_admin SSL: required
https://usosapps.amu.edu.pl/services/housing/assignments

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.

Get information on multiple assignments.
assignment_ids required Pipe-separated list of assignment IDs.
fields optional

Default value: id

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of assignment 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 required oauth_token for Token authorization.

Returned value:

A dictionary. Your assignment_ids will be its keys. Values will be assignment objects, or nulls, if no assignment by such ID was found (or your user does not have proper permissions to access it).

services/housing/check_in

Consumer: required Token: required Scopes: dorm_admin SSL: required
https://usosapps.amu.edu.pl/services/housing/check_in

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.

Check an user into dormitory. Only dormitory administrators can perform this action.
assignment_id required

The ID of the user's assignment. The user may have multiple assignments (e.g. for different academic terms), that's why we need a specific assignment ID here (instead of just user_id).
dormroom_id required ID of the room person will be checked into
check_in_date optional

Default value: (empty string)

Check-in date, if not given it defaults to now.

The residence registration period (check-in and planned check-out dates) must be contained within the period defined by the user's assignment.
check_out_date optional

Default value: (empty string)

Planned check-out date - if not given it defaults to a final day of the assignment period.

The residence registration period (check-in and planned check-out dates) must be contained within the period defined by the user's assignment.
resident_type_id optional

Default value: (empty string)

ID of the resident type - if not given it defaults to the value stored in the assignment (if there is no such value stored in the assignment, an error is raised).
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:

If a check in is successful, a following dictionary will be returned:

  • success - always true,
  • residence_id - ID of the newly created residence.

services/housing/check_out

Consumer: required Token: required Scopes: dorm_admin SSL: required
https://usosapps.amu.edu.pl/services/housing/check_out

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.

Check out a user from a dormitory. Only dormitory administrators can perform this action.
residence_id required

ID of the residence. This ID can be obtained from the residences field of the assignment method.
check_out_date optional

Default value: (empty string)

Check-out date. If not given it defaults to now.

The residence period (check-in and planned check-out dates) must fit within period defined in the user's assignment.
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:

On successful checkout {"success": true} will be returned. HTTP 4xx errors will be raised on error.

services/housing/dormitories

Consumer: optional Token: optional Scopes: n/a SSL: required
https://usosapps.amu.edu.pl/services/housing/dormitories

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.

Get information on multiple dormitories.
dormitory_ids required Pipe-separated list of dormitory IDs.
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 of dormitory 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 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. Your dormitory_ids will be its keys. Values will be dormitory objects, or nulls, if no dormitory by such ID was found.

services/housing/dormitory

Consumer: optional Token: optional Scopes: n/a SSL: required
https://usosapps.amu.edu.pl/services/housing/dormitory

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.

Get information on a single dormitory.
dormitory_id required ID of a dormitory.
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.
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:

  • id - ID of this dormitory;

  • name - name of a dormitory, a LangDict object;

  • short_name - a LangDict object with a very short "code" of thedormitory, can be empty (!);

  • can_i_manage - boolean; true if the requesting user has permissions to manage this dormitory;

  • dormrooms - a list of dormrooms available in this dormitory, or null if you don't have the access to see it.

    Every element on this list is of the same format as the one described in the dormroom method. You can use a subfield selector to access more subfields.

    You will need the dorm_admin scope in order to access this field. If you do have the scope, but your user doesn't have proper permissions, you will receive null here.

    The list will be ordered by room number.

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

services/housing/dormitory_index

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapps.amu.edu.pl/services/housing/dormitory_index

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.

Get the index of all dormitories in this USOS installation.
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 of dormitory method.

as_object optional

Default value: false

if true an object is returned instead of a list. The object will be of the same structure as the one returned by the dormroom_types 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 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:

An unordered list of dormitory objects.

services/housing/dormitory_user

Consumer: required Token: required Scopes: dorm_admin SSL: required
https://usosapps.amu.edu.pl/services/housing/dormitory_user

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.

Get information on a given user.

This is a clone of the services/users/user method, but some selected users can access broader selection of user- related data here, than they would be able via the original services/users/user method.

For example:

Let's say that the user X is a dormitory admin. He wants to know more on the user Y who has been awarded a place in his dormitory.

If X tries to access user Y's data via the services/users/user method, he will fail to see some fields, like student_number or pesel. This is because the original user method is (currently) not designed to check if user X is a dormitory admin, therefore it won't provide any additional details for him.

This method however IS designed to do so. If X tries to access user Y's data here, he will see much more.
user_id required

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 of services/users/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 required oauth_token for Token authorization.

Returned value:

The services/users/user object. If the referenced user does not exist, an error is raised.

services/housing/dormitory_users

Consumer: required Token: required Scopes: dorm_admin SSL: required
https://usosapps.amu.edu.pl/services/housing/dormitory_users

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.

Get information on multiple users. See dormitory_user method for more info.
user_ids required Pipe-separated 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 services/users/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 required oauth_token for Token authorization.

Returned value:

A dictionary. Your dormitory_ids will be its keys. Values will be dormitory objects, or nulls, if no dormitory by such ID was found.

services/housing/dormroom

Consumer: required Token: required Scopes: dorm_admin SSL: required
https://usosapps.amu.edu.pl/services/housing/dormroom

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.

Get information on a single dormitory room.

Note, that you'll get an error if your user doesn't have proper permissions to view this room.
dormroom_id required ID of a dormitory room.
fields optional

Default value: id

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 required oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • id - ID of this dormitory room;

  • number - room number (string, not an integer!);

  • type - an object describing the room type.

    As described in the dormroom_type method (subfields allowed).

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

  • dormitory - a parent dormitory of this room.

    As described in the dormitory method (subfields allowed).

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

  • capacity - integer, a maximum number of occupants.

services/housing/dormroom_type

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.amu.edu.pl/services/housing/dormroom_type

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.

Get information on a single dormroom type.

Dormitory rooms come in various standards and sizes. USOS defines a couple of room types, which roughly describe their size and standard.
dormroom_type_id required ID of the type of room
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 this type;

  • name - LangDict with a name of this type of room.

    In the majority of cases names will be reasonable short (e.g. "single rooms" or "quadruple room with bunk beds"). However, in theory, they may be even 200 characters long!

services/housing/dormroom_type_index

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.amu.edu.pl/services/housing/dormroom_type_index

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.

Get a list of all possible dormroom types currently defined in this USOS installation.
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 of dormroom_type method.

as_object optional

Default value: false

if true an object is returned instead of a list. The object will be of the same structure as the one returned by the dormroom_types 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:

A list of dormroom_type objects.

services/housing/dormroom_types

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.amu.edu.pl/services/housing/dormroom_types

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.

Get information on multiple dormroom types
dormroom_type_ids required Pipe-separated list of dormroom type IDs
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 of dormroom_type 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:

A dictionary: your dormroom_type_ids will be mapped to dictionary's keys, and each value will contain a dormroom_type object, or null, if no dormroom_type by given ID was found.

services/housing/dormrooms

Consumer: required Token: required Scopes: dorm_admin SSL: required
https://usosapps.amu.edu.pl/services/housing/dormrooms

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.

Get information on multiple dormitory rooms.
dormroom_ids required Pipe-separated list of dormitory room IDs.
fields optional

Default value: id

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of dormroom 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 required oauth_token for Token authorization.

Returned value:

A dictionary. Your dormroom_ids will be its keys. Values will be dormroom objects, or nulls, if no dormroom by such ID was found OR your user doesn't have proper permissions to see it.

services/housing/residence

Consumer: required Token: required Scopes: dorm_admin SSL: required
https://usosapps.amu.edu.pl/services/housing/residence

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.

Get information on a single residence.

A residence object represents a single check-in and check-out of a user to a dormitory dormroom.
residence_id required ID of a residence
fields optional

Default value: id

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 required oauth_token for Token authorization.

Returned value:

A dictionary of selected fields and their values.

Available fields:

  • id - ID of the residence;

  • assignment - an assignment object associated with this residence, or null if this residence has no such association.

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

  • user - a dormitory_user associated with this residence.

    Please note, that the assignment field may contain null, but the user will always contain some value.

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

  • dormroom - a dormroom to which the user has checked in.

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

  • check_in_date - datetime string; indicates when the user has checked in;

  • check_out_date - datetime string; indicates when the user has checked out OR (if its in the future) when he is planning to check out;

  • resident_type - a resident_type assigned to this user during this residence.

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

services/housing/residences

Consumer: required Token: required Scopes: dorm_admin SSL: required
https://usosapps.amu.edu.pl/services/housing/residences

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.

Get information on multiple residences.
residence_ids required Pipe-separated list of residence IDs.
fields optional

Default value: id

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of residence 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 required oauth_token for Token authorization.

Returned value:

A dictionary. Your residence_ids will be its keys. Values will be residence objects, or nulls, if no residence by such ID was found (or you don't have access to see it).

services/housing/resident_type

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.amu.edu.pl/services/housing/resident_type

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.

Get information on a single resident type.

Dormitory residents can be divided into several types, such as students, employees, or guests. A complete list of all valid resident types currently defined in this USOS installation can be retrieved with the resident_type_index method.
resident_type_id required ID of the type of resident
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 this type;

  • name - LangDict with a short name.

services/housing/resident_type_index

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.amu.edu.pl/services/housing/resident_type_index

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.

Get a list of all possible resident types currently defined in this USOS installation.
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 of resident_type method.

as_object optional

Default value: false

if true an object is returned instead of a list. The object will be of the same structure as the one returned by the dormroom_types 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:

A list of resident_type objects.

services/housing/resident_types

Consumer: ignored Token: ignored Scopes: n/a SSL: not required
https://usosapps.amu.edu.pl/services/housing/resident_types

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.

Get information on multiple resident types
resident_type_ids required Pipe-separated list of resident type IDs
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 of resident_type 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:

A dictionary: your resident_type_ids will be mapped to dictionary's keys, and each value will contain a resident_type object, or null, if no resident type by given ID was found.

services/housing/unused_assignment_ids

Consumer: required Token: required Scopes: dorm_admin SSL: required
https://usosapps.amu.edu.pl/services/housing/unused_assignment_ids

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.

Get a list of assignment IDs which were not checked-in yet. The list if filtered by dormitory and allocation period.

This method can be used by dormitory administrators to find the users who didn't check in into the dormitory. Only dormitory admins may access this list.
allocation_period_id required

ID of an allocation period.
dormitory_id required

ID of a dormitory.
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:

Unordered list of assignment IDs.
USOS API ver. 7.1.0.0-6, fb8dc698 (2024-10-15)