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

# Retrieve a person

> Return one prospect profile by exact email address.

Requires `people:read`.

Normalize the email to lowercase and URL-encode it before constructing the
request path.

```typescript theme={null}
const email = encodeURIComponent("maya@acme.example");
const path = `/api/v1/people/${email}`;
```


## OpenAPI

````yaml api-reference/openapi.json GET /api/v1/people/{email}
openapi: 3.1.0
info:
  title: Hobbes API
  description: >

    Use the Hobbes API to read your organization's analyzed demo sessions,

    prospects, accounts, transcripts, and funnel metrics, and to create and
    manage

    personalized Custom Links.


    **Authentication**: create an API key in Settings → API Keys, then send it

    as `Authorization: Bearer <key>` (or `x-api-key: <key>`). Keys are

    org-scoped; responses only ever contain your organization's data.


    **Scopes**: keys carry scopes (`sessions:read`, `people:read`,

    `accounts:read`, `analytics:read`, `transcripts:read`, `custom_links:read`,

    `custom_links:write`). `custom_links:write` also satisfies read access. Raw

    transcript access is a separate opt-in scope with a daily quota. Existing
    API

    keys do not receive Custom Link scopes automatically.


    **Rate limits**: keys allow 120 requests per minute by default. Responses

    include `X-RateLimit-Limit` and `X-RateLimit-Remaining`; 429 responses
    include

    `Retry-After`. Transcript access has a separate quota of 2,000 reads per

    organization per UTC day. Custom Link mutations are limited to 10 requests
    per

    minute per organization. Creation and thumbnail rendering also use weighted

    hourly and daily organization quotas, so one request containing 500 links is

    one HTTP request but consumes up to 500 creation and 500 render units.


    **Support**: every response carries an `X-Request-ID` header. Include it
    when

    reporting an issue so we can find the exact request in our logs.


    **Stability**: changes within v1 are additive only. Fields may be added to

    responses; existing fields are never removed or renamed.
  version: 1.0.0
servers:
  - url: https://api-us.hihobbes.com
    description: Production
security:
  - bearer: []
  - apiKeyHeader: []
tags:
  - name: Sessions
    description: Analyzed demo sessions and their transcripts.
  - name: People
    description: Prospect profiles aggregated across sessions.
  - name: Accounts
    description: Company-level engagement rollups by email domain.
  - name: Metrics
    description: Aggregate funnel performance over a trailing window.
  - name: Custom Links
    description: Create and manage personalized links.
  - name: Custom Link Jobs
    description: Poll, cancel, and retry asynchronous Custom Link work.
  - name: Custom Link Campaigns
    description: Organize Custom Links into campaigns.
paths:
  /api/v1/people/{email}:
    get:
      tags:
        - People
      summary: Retrieve a person
      description: >-
        Return one prospect profile by exact email address. URL-encode the email
        when constructing the request path.
      operationId: v1_get_person
      parameters:
        - name: email
          in: path
          required: true
          schema:
            type: string
            title: Email
            description: Exact prospect email address. URL-encode reserved characters.
          description: Exact prospect email address. URL-encode reserved characters.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PersonItem'
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
            X-RateLimit-Limit:
              description: Request limit for this key in the current 60-second window.
              schema:
                type: integer
                example: 120
            X-RateLimit-Remaining:
              description: Requests remaining for this key in the current window.
              schema:
                type: integer
                example: 119
        '401':
          description: API key required or invalid.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: API key required or invalid.
        '403':
          description: API key does not include the required scope.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: API key does not include the required scope.
        '404':
          description: Person not found in the key's organization.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: Person not found in the key's organization.
        '422':
          description: A path, query, header, or request field failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
        '429':
          description: Rate limit or organization quota exceeded.
          headers:
            X-Request-ID:
              description: Unique request identifier to include in support requests.
              schema:
                type: string
                example: req_01JABCDEF23456789
            X-RateLimit-Limit:
              description: Request limit for this key in the current 60-second window.
              schema:
                type: integer
                example: 120
            X-RateLimit-Remaining:
              description: Requests remaining for this key in the current window.
              schema:
                type: integer
                example: 119
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
                example: 30
            X-RateLimit-Reset:
              description: Unix timestamp when the limiting window resets.
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                required:
                  - detail
                properties:
                  detail:
                    type: string
                    example: Rate limit or organization quota exceeded.
components:
  schemas:
    PersonItem:
      properties:
        id:
          type: string
          title: Id
          description: Stable Hobbes person UUID.
          examples:
            - 0190a0b3-7f62-7df2-a52e-32b08f86c172
        email:
          anyOf:
            - type: string
            - type: 'null'
          title: Email
          description: Normalized prospect email.
          examples:
            - maya@acme.example
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Most recently captured prospect name.
          examples:
            - Maya Chen
        phone:
          anyOf:
            - type: string
            - type: 'null'
          title: Phone
          description: Most recently captured phone number.
          examples:
            - +1-415-555-0142
        business:
          anyOf:
            - type: string
            - type: 'null'
          title: Business
          description: Most recently captured company name.
          examples:
            - Acme
        totalSessions:
          anyOf:
            - type: integer
            - type: 'null'
          title: Totalsessions
          description: Sessions associated with this person.
          examples:
            - 3
        firstSeenAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Firstseenat
          description: First known session time.
          examples:
            - '2026-06-18T16:12:00Z'
        lastSeenAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Lastseenat
          description: Most recent known session time.
          examples:
            - '2026-07-10T18:42:16Z'
        totalTimeSpentSeconds:
          anyOf:
            - type: integer
            - type: 'null'
          title: Totaltimespentseconds
          description: Combined session time in seconds.
          examples:
            - 1842
        firstSource:
          anyOf:
            - type: string
            - type: 'null'
          title: Firstsource
          description: First captured acquisition source.
          examples:
            - google
        lastSource:
          anyOf:
            - type: string
            - type: 'null'
          title: Lastsource
          description: Most recent acquisition source.
          examples:
            - linkedin
        lastLocation:
          anyOf:
            - type: string
            - type: 'null'
          title: Lastlocation
          description: Most recent captured location.
          examples:
            - San Francisco, California, US
        qualificationStatus:
          title: Qualificationstatus
          description: 'Effective person qualification: qualified or unqualified.'
          examples:
            - qualified
          type: string
          enum:
            - qualified
            - unqualified
          default: unqualified
        buyingIntent:
          title: Buyingintent
          description: Overall person intent.
          examples:
            - high
          type: string
          enum:
            - low
            - medium
            - high
          default: low
        accountDomain:
          anyOf:
            - type: string
            - type: 'null'
          title: Accountdomain
          description: Registrable business email domain.
          examples:
            - acme.example
        summaryMarkdown:
          anyOf:
            - type: string
            - type: 'null'
          title: Summarymarkdown
          description: Markdown summary across this person's sessions.
          examples:
            - Maya is leading Acme's technical evaluation.
        qualificationRationale:
          anyOf:
            - type: string
            - type: 'null'
          title: Qualificationrationale
        qualificationSource:
          type: string
          enum:
            - automatic
            - manual
          title: Qualificationsource
          default: automatic
        qualificationAssessedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Qualificationassessedat
        qualificationRubricVersionId:
          anyOf:
            - type: string
            - type: 'null'
          title: Qualificationrubricversionid
        overallIntent:
          type: string
          enum:
            - low
            - medium
            - high
          title: Overallintent
          default: low
        intentScore:
          type: number
          maximum: 3
          minimum: 0
          title: Intentscore
          default: 0
        intentCalculatedAt:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Intentcalculatedat
      type: object
      required:
        - id
      title: PersonItem
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: Hobbes API key with the `hb_live_` prefix.
    apiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: Alternative to the Bearer authorization header.

````