UserCollectionResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/microsoft-entra/json-schema/microsoft-entra-user-collection-response-schema.json",
  "title": "UserCollectionResponse",
  "description": "Paged collection of user objects",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/microsoft-entra-users-api-openapi.yml#/components/schemas/UserCollectionResponse",
  "type": "object",
  "properties": {
    "@odata.context": {
      "type": "string",
      "description": "OData context URL"
    },
    "@odata.count": {
      "type": "integer",
      "description": "Total count of matching resources (if $count=true)"
    },
    "@odata.nextLink": {
      "type": "string",
      "format": "uri",
      "description": "URL to retrieve the next page of results"
    },
    "value": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/User"
      }
    }
  },
  "$defs": {
    "AssignedLicense": {
      "type": "object",
      "description": "Represents a license assigned to a user",
      "properties": {
        "disabledPlans": {
          "type": "array",
          "description": "Collection of unique identifiers for disabled service plans",
          "items": {
            "type": "string",
            "format": "uuid"
          }
        },
        "skuId": {
          "type": "string",
          "format": "uuid",
          "description": "Unique identifier for the SKU"
        }
      }
    },
    "PasswordProfile": {
      "type": "object",
      "description": "Contains the password profile associated with a user. The passwordProfile property of the user entity is a passwordProfile object.",
      "properties": {
        "password": {
          "type": "string",
          "writeOnly": true,
          "description": "The password for the user. Must satisfy the password complexity requirements of the tenant. Required on create."
        },
        "forceChangePasswordNextSignIn": {
          "type": "boolean",
          "description": "true if the user must change the password on the next sign-in; false otherwise",
          "default": false
        },
        "forceChangePasswordNextSignInWithMfa": {
          "type": "boolean",
          "description": "true if the user must perform multi-factor authentication before being forced to change the password",
          "default": false
        }
      }
    },
    "User": {
      "type": "object",
      "description": "Represents a Microsoft Entra ID user account. Contains identity, contact, organizational, and authentication properties.",
      "properties": {
        "id": {
          "type": "string",
          "readOnly": true,
          "description": "Unique identifier for the user (GUID). Assigned automatically by the directory."
        },
        "displayName": {
          "type": "string",
          "description": "The name displayed in the address book for the user"
        },
        "givenName": {
          "type": [
            "string",
            "null"
          ],
          "description": "The given name (first name) of the user"
        },
        "surname": {
          "type": [
            "string",
            "null"
          ],
          "description": "The surname (family name) of the user"
        },
        "mail": {
          "type": [
            "string",
            "null"
          ],
          "description": "The SMTP address of the user. This property cannot be set during creation for cloud-only users."
        },
        "userPrincipalName": {
          "type": "string",
          "description": "The user principal name (UPN) of the user in the format alias@domain. The domain must be present in the tenant's verified domains collection.",
          "format": "email"
        },
        "mailNickname": {
          "type": "string",
          "description": "The mail alias for the user. Must be specified when creating a new user."
        },
        "accountEnabled": {
          "type": "boolean",
          "description": "true if the account is enabled; otherwise, false. Must be specified when creating a new user."
        },
        "passwordProfile": {
          "$ref": "#/$defs/PasswordProfile"
        },
        "jobTitle": {
          "type": [
            "string",
            "null"
          ],
          "description": "The user's job title"
        },
        "department": {
          "type": [
            "string",
            "null"
          ],
          "description": "The department in which the user works"
        },
        "officeLocation": {
          "type": [
            "string",
            "null"
          ],
          "description": "The office location in the user's place of business"
        },
        "companyName": {
          "type": [
            "string",
            "null"
          ],
          "description": "The company name associated with the user"
        },
        "mobilePhone": {
          "type": [
            "string",
            "null"
          ],
          "description": "The primary cellular telephone number for the user"
        },
        "businessPhones": {
          "type": "array",
          "description": "The telephone numbers for the user's business",
          "items": {
            "type": "string"
          }
        },
        "streetAddress": {
          "type": [
            "string",
            "null"
          ],
          "description": "The street address of the user's place of business"
        },
        "city": {
          "type": [
            "string",
            "null"
          ],
          "description": "The city in which the user is located"
        },
        "state": {
          "type": [
            "string",
            "null"
          ],
          "description": "The state or province in the user's address"
        },
        "postalCode": {
          "type": [
            "string",
            "null"
          ],
          "description": "The postal code for the user's postal address"
        },
        "country": {
          "type": [
            "string",
            "null"
          ],
          "description": "The country or region in which the user is located (ISO 3166 two-letter code)"
        },
        "usageLocation": {
          "type": [
            "string",
            "null"
          ],
          "description": "Two-letter country code (ISO 3166). Required for users assigned licenses due to legal requirements for checking service availability."
        },
        "preferredLanguage": {
          "type": [
            "string",
            "null"
          ],
          "description": "The preferred language for the user in ISO 639-1 code format (e.g., en-US)"
        },
        "userType": {
          "type": "string",
          "description": "Classification of the user type relative to the tenant",
          "enum": [
            "Member",
            "Guest"
          ]
        },
        "employeeId": {
          "type": [
            "string",
            "null"
          ],
          "description": "The employee identifier assigned by the organization"
        },
        "employeeType": {
          "type": [
            "string",
            "null"
          ],
          "description": "Captures the type of worker (e.g., Employee, Contractor, Consultant, Vendor)"
        },
        "employeeHireDate": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "description": "The date and time when the user was hired"
        },
        "onPremisesSyncEnabled": {
          "type": [
            "boolean",
            "null"
          ],
          "readOnly": true,
          "description": "true if this user is synced from an on-premises directory; false if originally created in Azure AD; null if never synced"
        },
        "onPremisesSamAccountName": {
          "type": [
            "string",
            "null"
          ],
          "readOnly": true,
          "description": "The on-premises SAM account name synchronized from the on-premises directory"
        },
        "proxyAddresses": {
          "type": "array",
          "readOnly": true,
          "description": "List of proxy addresses for the user including SMTP and smtp prefixed addresses",
          "items": {
            "type": "string"
          }
        },
        "assignedLicenses": {
          "type": "array",
          "readOnly": true,
          "description": "Licenses assigned to the user",
          "items": {
            "$ref": "#/$defs/AssignedLicense"
          }
        },
        "createdDateTime": {
          "type": "string",
          "format": "date-time",
          "readOnly": true,
          "description": "The date and time the user was created"
        },
        "lastSignInDateTime": {
          "type": [
            "string",
            "null"
          ],
          "format": "date-time",
          "readOnly": true,
          "description": "The date and time of the user's most recent interactive sign-in activity"
        }
      }
    }
  }
}