Jump to

• Request
• Response
• Examples

Get User with Email Address

get

/documents/api/1.2/users/search/items

The service uses an email address as search text provided with the call to match a specific user. The search returns the matching user, if any.

Request

Supported Media Types

• application/json
• application/xml

Query Parameters

• email: string

  (Required) Specify an email address as a search string used to return a specific matching user. Wildcard characters are not supported.

Back to Top

Response

Supported Media Types

• application/json
• application/xml

200 Response

The request was fulfilled.

If no user is matched, count and errorCode will be "0" and items will not be returned.

Body ()

Root Schema : UsersResponse

Type: object

Folder metadata information.

Show Source

• count(optional): string
  The number of users found.
• errorCode(optional): string
  An error code of zero (0) indicates no errors.
• items(optional): array items
  Minimum Number of Items: 0

{
    "description":"Folder metadata information.",
    "properties":{
        "count":{
            "type":"string",
            "description":"The number of users found."
        },
        "errorCode":{
            "type":"string",
            "description":"An error code of zero (0) indicates no errors."
        },
        "items":{
            "type":"array",
            "items":{
                "$ref":"#/definitions/User"
            },
            "minItems":0
        }
    }
}

Nested Schema : items

Type: array

Minimum Number of Items: 0

Show Source

• Array of: object User
  User information

{
    "type":"array",
    "items":{
        "$ref":"#/definitions/User"
    },
    "minItems":0
}

Nested Schema : User

Type: object

User information

Show Source

• displayName(optional): string
  The display name for the user.
• id(optional): string
  Globally unique identifier (GUID) for the user.
• loginName(optional): string
  The login name for the user.
• type(optional): string
  Item type user.

{
    "description":"User information",
    "properties":{
        "id":{
            "type":"string",
            "description":"Globally unique identifier (GUID) for the user."
        },
        "displayName":{
            "type":"string",
            "description":"The display name for the user."
        },
        "loginName":{
            "type":"string",
            "description":"The login name for the user."
        },
        "type":{
            "type":"string",
            "description":"Item type <code>user</code>."
        }
    }
}

Example Response (application/json)

{
    "count":"1",
    "errorCode":"0",
    "items":[
        {
            "id":"U0EAA20910FAF3052ACB79E4T00000000001",
            "displayName":"User AA",
            "loginName":"userAALoginName",
            "type":"user"
        }
    ]
}

400 Response

Required field "email" is not provided.

Back to Top

Examples

The following example returns the user with the specified email address.

GET .../users/search/items?email=[e-mail]

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "count": "1",
    "errorCode": "0",
    "items": [
        {
            "type": "user",
            "id": "Tenant1.UserB",
            "displayName": "Tenant1 UserB",
            "loginName": "userBBLoginName"
        }
    ]
}

Example 2

The following example shows the results of a search for a user by email when no match is found.

GET .../users/search/items?email=[e-mail]

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 200

JSON Response

{
    "count": "0",
    "errorCode": "0"
}

Example 3

The following example shows the results of searching for a user without passing in the email parameter.

GET .../users/search/items?emailtypo=[e-mail]

Request Header

None.

Request Body

None.

HTTP Status Code

HTTP_STATUS = 400

JSON Response

{
    "count": "0",
    "errorCode": "-97",
    "errorKey": "!csUnableToRetrieveUserList!csRequiredFieldMissing2,dEmail",
    "errorMessage": "Unable to retrieve user list. The required field 'dEmail' is missing.",
    "title": "Unable to retrieve user list. The required field 'dEmail' is missing.",
    "type": "https://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html"
}

Back to Top