Get Login History

Purpose

This API provides a detailed log of login activities for organization accounts within a specified time range. It includes information such as display name, email address, login time, duration, IP address, browser details, and more.

OAuth Scope

Use the scope

ZohoMail.organization.accounts.ALL (or) ZohoMail.organization.accounts.READ

to generate the Authtoken.

ALL - Full access to accounts.

READ - Read access to accounts.

Request URL

Method: GET

https://mail.zoho.com/api/organization/{zoid}/accounts/reports/loginHistory

Path Parameters

  • zoid* long
    • This parameter denotes the unique Zoho Organization Identifier for the organization.
    • This parameter can be retrieved from the Get Organization Details API.

 

Query Parameters

  • mode* string
    • This parameter specifies the filter criteria for the login history.
    • Allowed values :
      • loginActivity - Retrieves successful login activities.
      • failedLoginActivity - Retrieves unsuccessful login activities.
      • protocolLoginActivity - Retrieves successful login activities through mail clients (POP, IMAP, etc.).
      • failedProtocolLoginActivity -Retrieves unsuccessful login activities through mail clients (POP, IMAP, etc.).
  • accessType string
    • This parameter specifies the type of access.
    • Allowed values :
      • all
      • web
      • mobile
    • The default value is all.
  • fromTime* long
    • Specifies the starting timestamp from which the login history records should be retrieved. 
    • The value of this parameter should be provided in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).
  • toTime* long
    • Specifies the ending timestamp to which the login history records should be retrieved. 
    • The value of this parameter should be provided in milliseconds since the Unix epoch (January 1, 1970, 00:00:00 UTC).
  • batchSize int
    • Specifies the number of login records to be included in each batch of the response.
    • Allowed value : 1-500.
    • The default value is 10.
  • scrollId string
    • This parameter is a unique identifier provided by the server in the response of the initial request. It allows users to retrieve subsequent batches of data for pagination purposes. When making subsequent requests to fetch additional data beyond the initial batch, the user includes this parameter to indicate from where to continue fetching data. 

 

* - Mandatory parameter

Note: This report is available for last 90 days records.

 

Response Codes

Refer here for the response codes and their meaning.

Sample Request

Copiedcurl "https://mail.zoho.com/api/organization/12345678/accounts/reports/loginHistory?toTime=1710394826000&fromTime=1707394825000&batchSize=10" \
-X GET \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization:Zoho-oauthtoken ***"

Sample Response

Copied{
    "status": {
        "code": 200,
        "description": "success"
    },
    "data": {
        "loginRecords": [
            {
                "displayName": "Test User",
                "loginDuration": -1,
                "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Postman/10.23.9 Electron/20.3.11 Safari/537.36",
                "serviceName": "Zoho Accounts",
                "primaryEmailAddress": "user@zylker.com",
                "zuid": 111111111,
                "accessType": "Web",
                "logoutTime": -1,
                "referrer": "accounts.zoho.com",
                "iPAddress": "172.24.206.59",
                "loginTime": 1709898360000,
                "mailboxAddress": "user@zylker.com",
                "userAgentObj": {
                    "os": "Mac OS X 10",
                    "browser": "Electron App 20",
                    "device": "Mac"
                },
                "emailAlias": [
                    "useralias@zylker.com"
                ],
                "isSuspiciousSignIn": false,
                "loginLocation": ""
            },
            {
                "displayName": "Test User2",
                "loginDuration": 267660000,
                "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.15; rv:123.0) Gecko/20100101 Firefox/123.0",
                "serviceName": "Mail",
                "primaryEmailAddress": "user2@zylker.com",
                "zuid": 22222222,
                "accessType": "Web",
                "logoutTime": 1710165900000,
                "referrer": "mail.zoho.com",
                "iPAddress": "172.24.206.59",
                "loginTime": 1709898240000,
                "mailboxAddress": "user2@zylker.com",
                "userAgentObj": {
                    "os": "Mac OS X 10",
                    "browser": "Firefox 123",
                    "device": "Mac"
                },
                "emailAlias": [
                    "user2alias@zylker.com"
                ],
                "isSuspiciousSignIn": false,
                "loginLocation": ""
            }
        ],
        "scrollId": "LoginHistory__2191773552742589985__8739554842535242676"
    }
}