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>
<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"
}
"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} |
|
| UAT URL | Full Data - https://accountws-uat.stanford.edu/accounts/{id} Lite Data - https://accountws-uat.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} | |
| UAT URL | https://accountws-uat.stanford.edu/accounts?type={type}&status={status}&statusdays={days} | |
| Query String | type - self/functional 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 |
|
| UAT URL | https://accountws-uat.stanford.edu/accounts/selfactive7days https://accountws-uat.stanford.edu/accounts/selfactive30days https://accountws-uat.stanford.edu/accounts/selfinactive7days https://accountws-uat.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 |
|
| UAT URL | https://accountws-uat.stanford.edu/accounts/funcactive7days https://accountws-uat.stanford.edu/accounts/funcactive30days https://accountws-uat.stanford.edu/accounts/funcinactive7days https://accountws-uat.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. | ||
