> ## Documentation Index
> Fetch the complete documentation index at: https://docs.athenahq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Look Up User By Email

> Resolves a user's `user_id` from their email address, scoped to your organization. The email is sent in the request body (not the URL) so it never lands in request logs or analytics. Returns the user only when they belong to your organization — either as an organization member (`access_type: "organization"`) or as an explicit member of at least one non-paused website in your organization (`access_type: "website"`). Any other case, including an email that belongs to a user in a different organization, returns `404` with the same body as a truly unknown email, so the endpoint cannot be used to enumerate accounts across tenants. Requires a global API key. Use the returned `user_id` with the member-management endpoints (e.g. list a user's websites or remove website access) without a discovery round-trip.



## OpenAPI

````yaml /api-reference/openapi.json post /api/v1/users/by-email
openapi: 3.1.0
info:
  title: AthenaHQ API
  description: >-
    AthenaHQ API provides programmatic access to manage your websites and
    prompts for AI-powered content optimization.
  version: 1.0.0
  contact:
    email: support@athenahq.ai
servers:
  - url: https://api.athenahq.ai
    description: Production server
security:
  - apiKey: []
tags:
  - name: Basics
    description: Core API operations for managing websites and prompts
  - name: Metrics
    description: Metrics and analytics endpoints for tracking AI visibility
  - name: Billing
    description: Billing and credits endpoints for managing usage
  - name: Team Management
    description: Endpoints for managing team members and invitations
  - name: Groups
    description: Endpoints for managing groups of websites
  - name: Content
    description: >-
      Endpoints for accessing Content Hub data — tabs, tracked URLs, and per-URL
      prompt breakdowns.
  - name: Pitch Workspace
    description: >-
      Endpoints for accessing pitch workspace reports — org-scoped pitch runs
      with competitors, prompts, attributes, and aggregate metrics.
paths:
  /api/v1/users/by-email:
    post:
      tags:
        - Team Management
      summary: Look Up User By Email
      description: >-
        Resolves a user's `user_id` from their email address, scoped to your
        organization. The email is sent in the request body (not the URL) so it
        never lands in request logs or analytics. Returns the user only when
        they belong to your organization — either as an organization member
        (`access_type: "organization"`) or as an explicit member of at least one
        non-paused website in your organization (`access_type: "website"`). Any
        other case, including an email that belongs to a user in a different
        organization, returns `404` with the same body as a truly unknown email,
        so the endpoint cannot be used to enumerate accounts across tenants.
        Requires a global API key. Use the returned `user_id` with the
        member-management endpoints (e.g. list a user's websites or remove
        website access) without a discovery round-trip.
      operationId: getUserByEmail
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - email
              properties:
                email:
                  type: string
                  format: email
                  description: Email address to look up. Matched case-insensitively.
      responses:
        '200':
          description: User found within your organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  user:
                    type: object
                    properties:
                      user_id:
                        type: string
                      email:
                        type: string
                      first_name:
                        type: string
                        nullable: true
                      last_name:
                        type: string
                        nullable: true
                      access_type:
                        type: string
                        enum:
                          - organization
                          - website
                        description: >-
                          `organization` when the user is a member of your
                          organization (implicit access to all its websites);
                          `website` when the user only has explicit membership
                          on one or more websites in your organization.
                    required:
                      - user_id
                      - email
                      - first_name
                      - last_name
                      - access_type
                required:
                  - user
        '400':
          description: Bad request - Invalid email format
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: Invalid email format
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - Global API key required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: 'Forbidden: global API key required'
        '404':
          description: Not found - No matching user in your organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              example:
                error: User not found
        '429':
          description: Too many requests - Rate limit exceeded. Retry after a short delay.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKey: []
components:
  schemas:
    Error:
      type: object
      description: Error response object
      required:
        - error
      properties:
        error:
          type: string
          description: Error message describing what went wrong
          example: Unauthorized
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        API key for authentication. You can create one
        [here](https://app.athenahq.ai/organization?tab=api).

````