Skip to end of metadata
Go to start of metadata

The Account resource allows you to search, create, read, update, delete, and perform other actions related to UW NetIDs. 

 

 

Attributes

IRWS Account Attributes describes all the attributes of the Account resource, as well as which attributes must be defined when performing certain operations (create, update, etc.) on a record.  

Actions

Note:  Your application may not be authorized for all of these actions.  

 

Reading a Record (GET)

You can read a record from the account resource with the following HTTP request:

GET {baseurl}/account/{accounttype}/{identifier}

where {baseurl} is the base URL for the service, {accounttype} is the type of account (account types are described under netid name in the Attribute List), and {identifier} is the UW NetID.  No payload is required, and it will be ignored if provided.

The response always includes an ETag header, which can be used on subsequent updates or deletes.


Searching for a Record

You can search for a record within the Account resource by executing a GET operation as follows:

GET {baseurl}/account

and providing search parameters via querystring or JSON payload (where {baseurl} is the base URL for the service) .  You must specify a search criteria for only one of the following primary searchable attributes:

  • validid  (must also specify source type...see details below)
  • ssn
  • lname
  • studentid
  • accid

See the Attribute Descriptions page for further information on these attributes.  

If you use validid as the search criteria, you must include the source type and the identifier for that source:

 

.../account?validid=uwhr=123456789

 

More examples are shown at the end of this section.  The validid search criteria supports searching by identifiers from all sources in the Identity Registry (uwhr, sdb, etc.).  

Search Results

IRWS will return a list of UW NetIDs matching the search criteria.  The search results will be in the following format:

{
  "account": [
    {
      "ledger": {
        "regid": "7FEC11D6AE3411D689DA0154AC494FFE",
        "accounts": {
			"personal": [
				"/account/personal/joespud"
			]
        }
      }
    }
  ],
  "totalcount": 1
}

There are a number of things to keep in mind about the search results.  

  • If you search by ssnstudentid, or validid, the registry will usually return a single identity associated with a single UW NetID.  
  • If more than one identity is returned, the identities will be in separate ledger objects.  
  • If more than one identity is returned, this is usually due to data entry errors, or because a person's different identities have not been correctly associated with one another.  
  • All UW NetIDs for an identity will be listed in the accounts object (not to be confused with the account array).  In most cases only one UW NetID will be listed, but if someone has changed their UW NetID, prior UW NetIDs will also be listed.   Active, personal NetIDs will be first in the list.  
  • Generally, a person will only have one active, personal UW NetID.  There are edge cases where a person may briefly have more than one active, personal UW NetID. 
  • You can look up the UW NetID at the given URL to verify its status.  Status codes are described on the Attributes Page.  
  • Additional UW NetIDs may be listed for administrator or other types of special accounts.  These will be labeled as such.  The different types of UW NetIDs are described on the Attributes Page.  

 

Search Algorithm

Searches are not case-sensitive.  The search algorithm for all attributes (with one exception) matches only on complete strings (e.g. "lname=john" would return only results for a person with the last name "john"--people named "johnson" would not be returned).  The following fields support wildcards in the search string:

  • lname

The supported wildcards are the asterisk (*) and question mark (?) regular expression operators.  Note that due to the large number of identities in the registry, it is not generally useful to search the account resource only by lname.  

Reminder: The question mark operator must be urlencoded if used in a querystring.

Searches by lname are normalized by removing spaces and punctuation marks, and then compared to a normalized version of the name in the registry. For example a search for lname "O'Malley" would be normalized to "omalley", and then return results for all people with an lname of "O'Malley", "OMalley", or "O Malley".

 

 

Examples

Search Queries

Most of these examples demonstrate query strings but a JSON payload example is provided at the end of this section.  

Search by Employee ID (i.e. validid with source type hepps)
{baseurl}/account?validid=uwhr=123456789
Search Only by Social Security Number
{baseurl}/account?ssn=123456789
Search Only by Student ID Number
{baseurl}/account?studentid=0123456
JSON Search Payload
{
 	"account": [
 		{
			 "validid":"uwhr=123456789"

	    }
 ]
}

 

 Search Results

These are some examples of different search results, and the way we recommend handling them.  

The following result indicates that the person you are searching for has two different identities in the the registry.  This generally means something needs to be corrected–we recommend you treat this as an error condition and contact help@uw.edu to evaluate the records. 

{
  "account": [
    {
      "ledger": {
        "regid": "7FEC11D6AE3411D689DAF454AC494FFE",
        "accounts": {
          "personal": [
			"/account/personal/joespud"
				]
        }
      }
  "ledger": {
          "regid": "24A03FCCAE3511D68CBC0004AC494FFE",
          "accounts": {
          "personal": [
			"/account/personal/uwinadm"
				]
         }
       }
    }
 ],
  "totalcount": 2
}

 

 

The following results indicate the person you are searching for has more than one UW NetID.  In these cases we recommend you use the first UW NetID in the list.  The first one will always be an active, personal UW NetID (in this example, "/account/personal/joespud").  

There is a very small chance a person could have more than one active, personal NetID at the time you search for them (this is a transient condition). We don't generally recommend you check for this, but the way to do this would be to look up each UW NetID at the given URL and see if the status is listed as active. You would treat a situation where a person has more than one active, personal NetID as an error condition and contact help@uw.edu to resolve the conflict.

{
  "account": [
    {
      "ledger": {
        "regid": "7FEC11D6AE3411D689DAF454AC494FFE",
        "accounts": {
          "personal": [
			"/account/personal/joespud",
			"/account/personal/joeold"
			]
		  "administrator": [
			"/account/administrator/admjoe"
				]
        }
      }
    }
 ],
  "totalcount": 1
}

 

The following results are what you will see most of the time–a single identity with a single personal UW NetID.  

{
  "account": [
    {
      "ledger": {
        "regid": "7FEC11D6AE3411D689DA0154AC494FFE",
        "accounts": {
          "personal": [
			"/account/personal/joespud"
				]
        }
      }
    }
  ],
  "totalcount": 1
}
  • No labels