Accessing phone numbers
:: services/phones 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 exposes raw access to all the phone numbers of various USOS entities. Please note that usually you won't need to use this module directly:

  • All the "popular" phone numbers are replicated into proper fields in many other methods, in order to by easily accessible without the need of a separate method call.

    For example, such methods as services/fac/faculty and services/users/user already contain the phone_numbers field.

  • You will need to use this module whenever you want to change these numbers. Currently, only Administrative Consumers can do that.

Methods

phone_number BETA Get phone number details
phone_type BETA get phone type
replace BETA Replace all phone numbers bound to the given entity. (administrative)
select BETA Get the phone numbers bound to the given entities. (administrative)

services/phones/phone_number

Consumer: optional Token: optional Scopes: n/a SSL: not required
https://usosapps.chopin.edu.pl/services/phones/phone_number

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 phone number details
phone_id required Identifier of a phone in database
fields optional

Default value: number|comment

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:

  • number - a string with the phone number, exactly as it is stored in the database.

    Please note, that it may contain spaces, dashes, parentheses and various other special characters, and sometimes even notes with complex utf-8 characters! This field is not guaranteed to contain a valid phone number (although it should!).

  • comment - a LangDict object, optional comment;

  • phone_type - phone type of selected phone number.

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

services/phones/phone_type

Consumer: ignored Token: ignored Scopes: n/a SSL: required
https://usosapps.chopin.edu.pl/services/phones/phone_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 phone type
id required Id of a type
fields optional

Default value: id|description

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 - Short code of a phone type;

  • description - Description of phone type.

services/phones/replace

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

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: required
https://usosapps.chopin.edu.pl/services/phones/replace

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.

Replace all phone numbers bound to the given entity.

This is a simple method allowing you to edit phone numbers of various entities. It has a limited functionality, but is quite easy to implement and should be enough in most cases. If you need extended funtionality, please contact us.

Unlike the select method, this method works with only a single entity. That is, if you want to change the numbers of two users, then you will have to call this method twice.

The changes made by this method are atomic - if any of the numbers fails to be saved, then none of them will be saved (nor the previous set of numbers will be removed).

Before each replace, it is advised to make the select call in order to make sure that your user sees the fresh content!
data required

JSON-encoded list with the descriptions of all the numbers to be saved.

The format of this list is very similar to the one described in the select method. Each entry on the list must be a dictionary, and:

  • It must contain the number and comment fields, as described in the select method. Please note, that currently only the Polish part of the comment's LangDict is stored (entries in other languages will be ignored).
  • It may contain the type_id field. If not given, then the value will be guessed (the guess is not guaranteed to be accurate). Also note, that type_id might be deprecated some time in the future - after this time its value will be silently ignored.

Note, that there might be some additional and undocumented restrictions. For example, some special characters could not be accepted in the number field, or the length of the comment could not exceed certain length. If the provided data fails these restrictions, then the error response will contain an appropriate message for the user.
fac_id optional

Default value: (empty string)

The ID of the faculty the numbers of which you want to edit.
user_id optional

Default value: (empty string)

The ID of the user the numbers of which you want to edit.

Note, that you can edit only personal phone numbers using this method. If you are looking for a way to edit official, work-related phone numbers of the staff members, then you should use the services/users/change method.
building_id optional

Default value: (empty string)

The ID of the building the numbers of which you want to edit.
dorm_id optional

Default value: (empty string)

The ID of the dormitory the numbers of which you want to edit.
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:

In case of success, HTTP 200 response with the {"success": true} content will be returned.

In case of failure, use the user_messages field to display a proper message for the user.

services/phones/select

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

Consumer: required (administrative) Token: ignored Scopes: n/a SSL: required
https://usosapps.chopin.edu.pl/services/phones/select

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 phone numbers bound to the given entities.

You can retrieve the phone numbers of multiple entities at the same time, but all of these entities must be of the same class. So, for example, if you want to get the numbers of faculties X and Y, and of the user Z, then you must call this method twice - once with the fac_id=X|Y parameter, and then again with user_id=Z.

Note, that although all the parameters are optional, you still must use at least one of them in order to get the results. The IDs of the entities are not validated (empty lists will be returned for non-existing entities).
fields optional

Default value: number|comment

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

fac_ids optional

Default value: (empty string)

List of faculty IDs.
user_ids optional

Default value: (empty string)

List of user IDs. Note, that this method will return only personal phone numbers of these users. If you are looking for offical, work-related phone numbers of staff members, then you should use the phone_numbers field of the services/users/user method.
building_ids optional

Default value: (empty string)

List of building IDs.
dorm_ids optional

Default value: (empty string)

List of dormitory IDs.
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 with all the entity IDs mapped to its keys. For every key, its value will contain the (unordered) list of phone numbers associated with the entity by this ID. Each phone number will be represented as a dictionary of the following structure:

  • number - a string with the phone number, exactly as it is stored in the database.

    Please note, that it may contain spaces, dashes, parentheses and various other special characters, and sometimes even notes with complex utf-8 characters! This field is not guaranteed to contain a valid phone number (although it should!).

  • comment - a LangDict object, optional comment;

  • type_id - string with a "phone type code".

    This used to indicate the type of the phone number (e.g. "STA" for landline, "KOM" for mobile, "FAX" for fax), but it is quite obsolete nowadays (and purposefully underdocumented). Our advice is not to use this field.
USOS API ver. 7.0.4.0-2, 9b190706, dirty (2024-06-10)