Skip to content Skip to site navigation Skip to service navigation

Account RESTful Web Service API

The Account web service provides a way to retrieve lists of accounts and account details given a SUNet ID.

This includes:

  • Getting Single Account details given a SUNet ID
  • List of accounts that changed status in past x days
  • Support shortcut URLS — Active/Inactive SELF and FUNCTIONAL accounts

How to get started with the Account API

Follow the Middleware and Integration Services Integration (MaIS) checklist for RESTful Web Services. If you need help, are not sure whether the Web APIs are the best method for integrating with the registry, or just have some questions, contact the MaIS team.

HTTP Status codes

Code Conditions
200 OK The usual successful return code.
400 Bad Request Missing required parameters or identifier is in wrong format.
403 Access Denied The request was made without valid certificate.
404 Not Found The record you're looking for doesn't exist.
500 Internal Server Error Something broke with our code. Please tell us about it.

Error Handling

Account API sends error status via standard HTTP status codes (4xx or 5xx) and always returns an XML/JSON document detailing the error.


An example of XML error document:

<AccountWsError>
      <status>404</status>
      <message>Account [xxxxx] not found</message>
      <url>https://accountws.stanford.edu/accounts/xxxxx</url>
</AccountWsError>

 

An example of JSON error document:

{
"status": 400,
"message": "Valid number of 'statusdays' is 1..30",
"url": "https://accountws.stanford.edu/accounts?type=self&status=inactive&statusdays=355"
}

 

Return format

There are 2 formats Accountws supports, XML and JSON. By default, the return format is JSON if no Accept header is specified. User can also specify application/json as the Accept header to receive JSON. In browsers, the default Accept header is application/xml so data is returned in XML format.

 

Get Single Account details

Description Get Single Account details by sunetid or functional account name. The data can be full/lite data.
URL Full Data - https://accountws.stanford.edu/accounts/{id}
Lite Data - https://accountws.stanford.edu/accounts/lite/{id}
Method GET
Returns 200 & Account details
403 & Not authorized to access the service.
404 & error: id is invalid.
Id should be sunetid.
 

List of accounts that changed status in past x days

Description List of active/inactive accounts of which the status has changed in the past x days.
(returns only lite format)
URL https://accountws.stanford.edu/accounts?type={type}&status={status}&statusdays={days}
Query String type - Self/Funtional
status - active/inactive/pending
days - 1 to 30
Method GET
Returns 200 & List of active/inactive accounts in lite format
403 & error: Not authorized to access the service.
404 & error: Input invalid.
 

Support shortcut URLS - Active/Inactive SELF accounts

Description Support shortcut URLS for active/inactive SELF accounts that changed status in the last 7/30 days.
(returns only lite format)
URL https://accountws.stanford.edu/accounts/selfactive7days
https://accountws.stanford.edu/accounts/selfactive30days
https://accountws.stanford.edu/accounts/selfinactive7days
https://accountws.stanford.edu/accounts/selfinactive30days
Method GET
Returns 200 & List of active/inactive SELF accounts
403 & error: Not authorized to access the service.
404 & error: Input invalid.

 

Support shortcut URLS - Active/Inactive FUNCTIONAL accounts

Description Support shortcut URLS for active/inactive FUNCTIONAL accounts that changed status in the last 7/30 days.
(returns only lite format)
URL https://accountws.stanford.edu/accounts/funcactive7days
https://accountws.stanford.edu/accounts/funcactive30days
https://accountws.stanford.edu/accounts/funcinactive7days
https://accountws.stanford.edu/accounts/funcinactive30days
Method GET
Returns 200 & List of active/inactive FUNCTIONAL accounts
403 & error: Not authorized to access the service.
404 & error: Input invalid.
Last modified January 17, 2017