---
title: "Discover User Identities"
method: POST
path: "/database/{version}/{container}/{environment}/{database}/users/discover"
tags: ["Users"]
---

# Discover User Identities

`POST /database/{version}/{container}/{environment}/{database}/users/discover`

Discover all user identities based on email addresses or user record names

## Path parameters

- `version` string, required — Protocol version
- `container` string, required — Container ID (begins with "iCloud.")
- `environment` 'development' | 'production', required — Container environment
- `database` 'public' | 'private' | 'shared', required — Database scope

## Request body

- object
  - `lookupInfos` object[]
    - `emailAddress` string
    - `phoneNumber` string
    - `userRecordName` string

## Response `200`

User identities discovered successfully

- DiscoverResponse
  - `users` UserIdentity[]
    - `userRecordName` string — The record name of the user
    - `nameComponents` NameComponents — The parts of a user's name
      - `namePrefix` string — The user's name prefix
      - `givenName` string — The user's first name
      - `middleName` string — The user's middle name
      - `familyName` string — The user's last name
      - `nameSuffix` string — The user's name suffix
      - `nickname` string — The user's nickname
      - `phoneticRepresentation` string — A phonetic representation of the user's name
    - `lookupInfo` UserIdentityLookupInfo — Information used to look up a user identity
      - `emailAddress` string — The user's email address
      - `phoneNumber` string — The user's phone number
      - `userRecordName` string — The record name of the user

## Other responses

- `400` — Error response shared by all endpoints. The body schema is the same for every 4xx/5xx status code; the HTTP status code itself disambiguates which CloudKit failure occurred. See Apple's CloudKit Web Services Error Codes documentation for the full code → status mapping: - 400 BadRequest (BAD_REQUEST, ATOMIC_ERROR) - 401 Unauthorized (AUTHENTICATION_FAILED) - 403 Forbidden (ACCESS_DENIED) - 404 NotFound (NOT_FOUND, ZONE_NOT_FOUND) - 409 Conflict (CONFLICT, EXISTS) - 412 PreconditionFailed (VALIDATING_REFERENCE_ERROR) - 413 RequestEntityTooLarge (QUOTA_EXCEEDED) - 421 UnprocessableEntity (AUTHENTICATION_REQUIRED) - 429 TooManyRequests (THROTTLED) - 500 InternalServerError (INTERNAL_ERROR) - 503 ServiceUnavailable (TRY_AGAIN_LATER)
- `401` — Error response shared by all endpoints. The body schema is the same for every 4xx/5xx status code; the HTTP status code itself disambiguates which CloudKit failure occurred. See Apple's CloudKit Web Services Error Codes documentation for the full code → status mapping: - 400 BadRequest (BAD_REQUEST, ATOMIC_ERROR) - 401 Unauthorized (AUTHENTICATION_FAILED) - 403 Forbidden (ACCESS_DENIED) - 404 NotFound (NOT_FOUND, ZONE_NOT_FOUND) - 409 Conflict (CONFLICT, EXISTS) - 412 PreconditionFailed (VALIDATING_REFERENCE_ERROR) - 413 RequestEntityTooLarge (QUOTA_EXCEEDED) - 421 UnprocessableEntity (AUTHENTICATION_REQUIRED) - 429 TooManyRequests (THROTTLED) - 500 InternalServerError (INTERNAL_ERROR) - 503 ServiceUnavailable (TRY_AGAIN_LATER)

## Changes

- **2026-04-29** `c2b3dfb861bb` — 4 warning, 3 info
  - removed the request property `users`
  - removed the optional property `users/items/emailAddress` from the response with the `200` status
  - removed the optional property `users/items/firstName` from the response with the `200` status
  - removed the optional property `users/items/lastName` from the response with the `200` status
  - …3 more
- **2025-07-06** `a17a324ec78e` — 1 info
  - endpoint added
- **2025-07-05** `a6d50d6e9dde` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/brightdigit/apis/apple-cloudkit-web-services-api/changes/database/:version/:container/:environment/:database/users/discover/post.md)

---

[API](https://skmtc.dev/brightdigit/apis/apple-cloudkit-web-services-api.md) · [All operations](https://skmtc.dev/brightdigit/apis/apple-cloudkit-web-services-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/brightdigit/apple-cloudkit-web-services-api/revisions/db45a101c485/schema)