Search
Search Web Services, optional, provide your application with users' latest profile information. If a user's name or email address has changed in his or her NYC.ID profile, the info stored in your application may be outdated. The Search Web Services may be invoked to get the latest info for certain operations, such as emailing your users in a batch process. Learn about Web Services.
Get User Web Service
Your application may use this service to get a JSON-formatted user.
GET /account/api/user.htm
Input
| Parameter Name | Parameter Description | Optional/Required |
|---|---|---|
| guid | A user's guid | Required, if email is not specified |
| The user's email address (i.e., mail) from the SAML Assertion | Required, if guid is not specified | |
| dateTime | The current date and time formatted as a Java SimpleDateFormat pattern (MM/dd/yyyy HH:mm or M/d/yy HH:mm). |
Optional, unless your application's NYC.ID Service Account is configured to prevent replay attacks |
| userName | Your application's NYC.ID Service Account username | Required |
| signature | The signature generated for this request. Refer to calculating the authentication signature | Required |
Output
| Http Status (Code) | Response | Description |
|---|---|---|
| OK (200) | A JSON-formatted user. | Indicates the user was found |
| BAD REQUEST (400) | Refer to Bad Request Status table below | Indicates there was an error in the http request |
| UNAUTHORIZED (401) | Refer to Unauthorized Status table below | Indicates there was an error in the http request related to authentication |
| INTERNAL SERVER ERROR (500) | Refer to Internal Server Error Status table below | Indicates there was an error while processing the http request |
| SERVICE UNAVAILABLE (503) | Not Applicable | Indicates the server is undergoing maintenance and is temporarily unavailable |
Bad Request Status
A bad request status indicates there was a problem with the http request. Each http response contains one or more error codes and messages. Refer to the table below for descriptions.
Here is a sample error:
{"ERRORS":{"guid":"invalid","userName":"required","signature":"required"}}
| Code | Message | Description |
|---|---|---|
| guid | invalid | "guid" was not provided or was not in the required format. |
| invalid | email address was invalid. | |
| userName | invalid | "userName" was not provided or was invalid. |
| signature | invalid | "signature" was not provided or was not in the required format. |
| cpui.unknownGuid | Unknown GUID: <guid> | If "guid" was not found |
| cpui.unknownEmail | Unknown Email: <email> | If "email" was not found. |
Unauthorized Status
An unauthorized status indicates there was a problem with the http request related to authentication. Each http response contains one or more error codes and messages. Refer to the table below for descriptions.
Here is a sample error:
{"ERRORS":{"cpui.failedToAuthenticate":"The combination of userName and signature is incorrect."}}
| Code | Message | Description |
|---|---|---|
| cpui.invalidDomainName | Invalid Domain Name: <domainName>. Valid Domains: [doitt.nycnet, nyc.gov, nycid.nycnet, csc.nycnet, cloudapp.net, hpd.nycnet, nycgovparks.org, finance.nycnet, hpdnyc.org, cs.nycnet, gcomsoft.com, records.nycnet, dcas.nycnet, dhs.nycnet, redcapcloud.com, cityofnewyork.us, dynamics.com, dynamics365portals.us, getinfo.nyc, fdnycloud.org, microsoftonline.com, mkscloud.com, samaritan.com, ivalua.us, sbs.nycnet, communityneeds.nyc, ukrosoft.com.ua, appgeo.com, azurewebsites.net, or gigya.com] | The referrer domain name was invalid. |
| cpui.failedToAuthenticate | The combination of userName and signature is incorrect. | Authentication failed. Either "userName" or "signature" was incorrect or "dateTime", if provided, differs by more than 15 minutes from the current date and time. |
| cpui.unauthorized | The search is unauthorized. | The service account, "userName", does not have permission to search for this user.
! IMPORTANT: Only users that have logged into the application with the service account, "userName", can be searched. |
Internal Server Error Status
An internal server error status indicates there was a problem while processing the http request. Each http response contains one or more error codes and messages. Refer to the table below for descriptions.
| Code | Message | Description |
|---|---|---|
| cpui.exception | This value is dynamically computed based on the cause of the error. For those that are curious, it's the output of the getMessage() method of the java.lang.Exception class. |
Indicates an unknown error occurred while processing the request |
Get Users Web Service
Your application may use this web service to get a list of users:
- whose profile has been modified between a specified start date and optional end date, or
- by specifying one or more guids
! IMPORTANT: In the event that the list contains more than 1,000 users, an error will be returned. You application may need to make multiple requests with a smaller date range to get the complete list of users that have been modified between the original start date and end date. Refer to Get Users Example below.
GET /account/api/getUsers.htm
Input
| Parameter Name | Parameter Description | Optional/Required |
|---|---|---|
| startDate | The user's profile must have been modified at or after this date. The startDate should be formatted as a Java SimpleDateFormat pattern (MM/dd/yyyy HH:mm or M/d/yy HH:mm). |
Required, if "guids" is not specified |
| guids | A user's "guid" from the SAML Assertion. This parameter may be specified multiple times. | Required, if "startDate" is not specified |
| endDate | The user's profile must have been modified at or before this date. The endDate
should be formatted as a Java SimpleDateFormat pattern (MM/dd/yyyy HH:mm or M/d/yy HH:mm). |
Optional, defaults to the current date |
| dateTime | The current date and time formatted as a Java SimpleDateFormat pattern (MM/dd/yyyy HH:mm or M/d/yy HH:mm). |
Optional, unless your application's NYC.ID Service Account is configured to prevent replay attacks |
| userName | Your application's NYC.ID Service Account username | Required |
| signature | The signature generated for this request. Refer to calculating the authentication signature | Required |
Output
| Http Status (Code) | Response | Description |
|---|---|---|
| OK (200) | A JSON-formatted user! IMPORTANT: Only users that have logged into the application with the service account, "userName", will be returned. |
If no users are found, an empty JSON array will be returned. |
| BAD REQUEST (400) | Refer to Bad Request Status table below | Indicates there was an error in the http request |
| UNAUTHORIZED (401) | Refer to Unauthorized Status table below | Indicates there was an error in the http request related to authentication |
| INTERNAL SERVER ERROR (500) | Refer to Internal Server Error Status table below | Indicates there was an error while processing the http request |
| SERVICE UNAVAILABLE (503) | Not Applicable | Indicates the server is undergoing maintenance and is temporarily unavailable |
Bad Request Status
A bad request status indicates there was a problem with the http request. Each http response contains one or more error codes and messages. Refer to the table below for descriptions.
Here are a few sample errors:
{"ERRORS":{"startDate":"required","guids":"required","userName":"required","signature":"required"}}
{"ERRORS":{"startDate":"Invalid startDate format. Expect MM/dd/yyyy HH:mm format."}}
{"ERRORS":{"startDate":"Invalid startDate date. Expect a past date."}}
{"ERRORS":{"cpui.sizeLimit":"Number of users returned exceeds size limit."}}
| Code | Message | Description |
|---|---|---|
| startDate | required | "startDate" or "guids" was not provided. |
| startDate | Invalid startDate date. Expect a past date. | "startDate" was a future date. |
| endDate | invalid | "endDate" was equal to the "startDate" or "endDate" was before "startDate". |
| endDate | Invalid endDate date. Expect a past date. | "endDate" was a future date. |
| endDate | Invalid endDate format. Expect MM/dd/yyyy HH:mm format. |
"endDate" was not in the required format. |
| guids | required | "startDate" or "guids" was not provided. |
| guids | size must be between 1 and 100 | "guids" was not specified or exceeds the maximum size limit. |
| userName | invalid | "userName" was not provided or was invalid. |
| signature | invalid | "signature" was not provided or was not in the required format. |
| cpui.sizeLimit | Number of users returned exceeds size limit. | More than 1,000 users were modified between the "startDate" and "endDate". |
Unauthorized Status
An unauthorized status indicates there was a problem with the http request related to authentication. Each http response contains one or more error codes and messages. Refer to the table below for descriptions.
Here is a sample error:
{"ERRORS":{"cpui.failedToAuthenticate":"The combination of userName and signature is incorrect."}}
| Code | Message | Description |
|---|---|---|
| cpui.invalidDomainName | Invalid Domain Name: <domainName>. Valid Domains: [doitt.nycnet, nyc.gov, nycid.nycnet, csc.nycnet, cloudapp.net, hpd.nycnet, nycgovparks.org, finance.nycnet, hpdnyc.org, cs.nycnet, gcomsoft.com, records.nycnet, dcas.nycnet, dhs.nycnet, redcapcloud.com, cityofnewyork.us, dynamics.com, dynamics365portals.us, getinfo.nyc, fdnycloud.org, microsoftonline.com, mkscloud.com, samaritan.com, ivalua.us, sbs.nycnet, communityneeds.nyc, ukrosoft.com.ua, appgeo.com, azurewebsites.net, or gigya.com] | The referrer domain name was invalid. |
| cpui.failedToAuthenticate | The combination of userName and signature is incorrect. | Authentication failed. Either "userName" or "signature" was incorrect or "dateTime", if provided, differs by more than 15 minutes from the current date and time. |
Internal Server Error Status
An internal server error status indicates there was a problem while processing the http request. Each http response contains one or more error codes and messages. Refer to the table below for descriptions.
| Code | Message | Description |
|---|---|---|
| cpui.exception | This value is dynamically computed based on the cause of the error. For those that are curious, it's the output of the getMessage() method of the java.lang.Exception class. |
Indicates an unknown error occurred while processing the request |
JSON-Formatted Users
A user contains the following fields:
| Name | Description |
|---|---|
| id | The user's GUID |
| The user's email address | |
| firstName | The user's first name, if available |
| middleInitial | The user's middle initial, if available |
| lastName | The user's last name, if available |
| validated | The user's email validation status. A value of true indicates the user has validated his or her email address. |
| active | The user's activation status. A value of true indicates the user can login. |
| nycEmployee | A value of true indicates the user is a NYC Employee and the account is not linked to a NYC account nor social account. |
| hasNYCAccount | A value of true indicates the user has an NYC account and can authenticate via the Authenticate Web Service. |
| tfa | A value of true indicates the user has two factor authentication enabled |
Here is a sample JSON-formatted user:
{
"id": "LYUKZYDI",
"email": "test_1237232535839073773@doitt.nyc.gov",
"validated": true,
"active": true,
"nycEmployee": false,
"hasNYCAccount": true,
"tfa": false
}
Here is a sample JSON-formatted array of users:
[
{
"id": "WWITE36D",
"userType": "EDIRSSO",
"email": "test_64236034890058192@doitt.nyc.gov",
"validated": true,
"active": true,
"nycEmployee": false,
"hasNYCAccount": true,
"tfa": false
},
{
"id": "R4D2EVYT",
"email": "test_1565418353006838329@doitt.nyc.gov",
"validated": false,
"active": true,
"nycEmployee": false,
"hasNYCAccount": true,
"tfa": false
},
{
"id": "UDTX6W2I",
"email": "test_-2708049796154665029@doitt.nyc.gov",
"validated": true,
"active": true,
"nycEmployee": false,
"hasNYCAccount": true,
"tfa": false
},
{
"id": "LG4BAOGE",
"email": "test_-5194663058558967871@doitt.nyc.gov",
"validated": true,
"active": true,
"nycEmployee": false,
"hasNYCAccount": true,
"tfa": false
}
]
Get Users Example
If the Get Users Web Service determines that there are more than 1,000 users modified between the start and end dates, NYC.ID will return an error. To work around this limitation, your application should make multiple requests with a smaller date range to get the full list of users. The example Java code below demonstrates this process using recursion. Each recursion divides the time span equally and continues making requests with smaller and smaller times spans until all users have been returned.
private List<User> getUsersByTimeSpan(Date startDate, Date endDate) throws QueryExceedsSizeLimitException {
List<User> users = new ArrayList<User>();
long timeSpan = (endDate.getTime() - startDate.getTime());
if (timeSpan < 60000) { // cannot be less than 1 minute (60000 milliseconds)
throw new QueryExceedsSizeLimitException();
}
String signatureParams = getSignatureParams(startDate, endDate);
String signature = getSignature(signatureParams, "password");
String usersResponse = sendRequest(startDate, endDate, signature);
if (usersResponse.contains("cpui.sizeLimit")) {
System.out.println("Query size limit exceeded: " + getDateString(startDate) + ", " + getDateString(endDate));
users.addAll(getUsersByTimeSpan(startDate, new Date(startDate.getTime() + timeSpan/2)));
users.addAll(getUsersByTimeSpan(new Date(startDate.getTime() + timeSpan/2), endDate));
} else {
users.addAll(getUsersFromJSON(usersResponse));
System.out.println("Adding " + users.size() + " users: " + getDateString(startDate) + ", " + getDateString(endDate));
}
return users;
}