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
email 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.
email 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: [[an error occurred while processing this directive]] 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: [[an error occurred while processing this directive]] 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
email 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.

 

Here is a sample JSON-formatted user:

{
  
  "id": "LYUKZYDI",
"email": "test_1237232535839073773@doitt.nyc.gov",
"validated": true,
"active": true,
"nycEmployee": false,
"hasNYCAccount": true }

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
},
{
"id": "R4D2EVYT",
"email": "test_1565418353006838329@doitt.nyc.gov",
"validated": false,
"active": true,
"nycEmployee": false,
"hasNYCAccount": true
},
{
"id": "UDTX6W2I",
"email": "test_-2708049796154665029@doitt.nyc.gov",
"validated": true,
"active": true,
"nycEmployee": false,
"hasNYCAccount": true
},
{
"id": "LG4BAOGE",
"email": "test_-5194663058558967871@doitt.nyc.gov",
"validated": true,
"active": true,
"nycEmployee": false,
"hasNYCAccount": true
}
]

 

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; }