Institutional addresses
:: services/instaddr 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 you to get information on institutional addresses and modify it if you have proper administrative privileges.

Methods

all BETA Get a list of all institutional addresses. (administrative)
create BETA Create institutional address. (administrative)
delete BETA Delete institutional addresses. (administrative)
inst_address BETA Get information on a given institutional address.
inst_addresses BETA Get information on multiple institutional addresses. (administrative)
update BETA Update an institutional address. (administrative)
update_user BETA Update user institutional addresses. (administrative)
user BETA Get user's institutional addresses. (administrative)

services/instaddr/all

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

Consumer: required (administrative) Token: optional Scopes: n/a SSL: not required
https://apps.umcs.pl/services/instaddr/all

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

Currently calling this method with access token causes a method_forbidden error.
fields optional

Default value: id|name|email

Selector of result fields you are interested in. The selector must contain subset of primary fields, which are described in the returns section of inst_address 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 list of dictionaries describing institutional addresses (as returned by inst_address method).

services/instaddr/create

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

Consumer: required (administrative) Token: optional Scopes: n/a SSL: not required
https://apps.umcs.pl/services/instaddr/create

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.

Create institutional address.

Currently calling this method with access token causes a method_forbidden error.
name required

LangDict with the name of the institutional address. No more than 100 characters.

Currently English name of the institutional address is ignored.
email required

Email of the institutional address. No more than 100 characters.
fac_id required

Faculty ID. Only administrators from this faculty will be able to modify it and change assigned users.
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 the following structure:

  • inst_address_id - institutional address ID.

Thrown errors:

  • object_invalid - object is in invalid state.

    Possible reasons:

    • email_duplicated - email address is already in use.

  • object_not_found - faculty could not be found; param_name is equal to fac_id.

services/instaddr/delete

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

Consumer: required (administrative) Token: optional Scopes: n/a SSL: not required
https://apps.umcs.pl/services/instaddr/delete

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.

Delete institutional addresses.

Currently calling this method with access token causes a method_forbidden error.
inst_address_ids required

List of institutional address 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. Plus optional oauth_token for Token authorization.

Returned value:

A dictionary of the following structure:

  • matched - a list of instututional address IDs which were actually deleted.

services/instaddr/inst_address

Consumer: required Token: optional Scopes: mailclient SSL: not required
https://apps.umcs.pl/services/instaddr/inst_address

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 institutional address.
inst_address_id required

Institutional address ID.
fields optional

Default value: id|name|email

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:

  • Primary:

    • id - institutional address ID;

    • name - name of the institutional address (a LangDict object);

    • email - institutional address email;

    • faculty - faculty of the institutional address.

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

  • Secondary:

    • assigned_users - list of users that can send messages from this institutional address.

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

Thrown errors:

  • object_not_found - institutional address could not be found; param_name is equal to inst_address_id.

services/instaddr/inst_addresses

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

Consumer: required (administrative) Token: optional Scopes: n/a SSL: not required
https://apps.umcs.pl/services/instaddr/inst_addresses

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 institutional addresses.
inst_address_ids required

List of institutional address IDs.
fields optional

Default value: id|name|email

Selector of result fields you are interested in. The selector may contain any subset of fields, which are described in the returns section of inst_address 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 mapping institutional address IDs to dictionaries describing the addresses (as returned by inst_address method). If specified address could not be found, null is returned instead of a dictionary.

services/instaddr/update

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

Consumer: required (administrative) Token: optional Scopes: n/a SSL: not required
https://apps.umcs.pl/services/instaddr/update

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.

Update an institutional address.

Currently calling this method with access token causes a method_forbidden error.
inst_address_id required

Institutional address ID.
name required

LangDict with the name of the institutional address. No more than 100 characters.

Currently English name of the institutional address is ignored.
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:

An empty dictionary returned if the method has been executed successfully. Some keys may be added in the future.

Thrown errors:

  • object_not_found - institutional address could not be found; param_name is equal to inst_address_id.

services/instaddr/update_user

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

Consumer: required (administrative) Token: optional Scopes: n/a SSL: not required
https://apps.umcs.pl/services/instaddr/update_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.

Update user institutional addresses.

Currently calling this method with access token causes a method_forbidden error.
user_id required

User ID.
inst_address_ids required

List of institutional address 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. Plus optional oauth_token for Token authorization.

Returned value:

An empty dictionary returned if the method has been executed successfully. Some keys may be added in the future.

services/instaddr/user

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

Consumer: required (administrative) Token: required Scopes: n/a SSL: not required
https://apps.umcs.pl/services/instaddr/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 a list of institutional addresses assigned to the user. Such addresses may be used in services/mailclient module to send email messages.
fields optional

Default value: id|name|email

Selector of result fields you are interested in. The selector must contain subset of primary fields, which are described in the returns section of inst_address method.

user_id optional

Default value: (access token issuer)

ID of a user.
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 describing institutional addresses (as returned by inst_address method).
USOS API ver. 7.1.0.0-4, 0e1fe7fc, dirty (2024-08-27)