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

# Enrich a person

> Submit one personal email. Hanto returns a final synchronous result.

Only the `email` field is accepted. Requests with extra fields return `400` with `{"error":"invalid_request"}`.


## OpenAPI

````yaml /openapi.json post /api/v1/person/enrich
openapi: 3.1.0
info:
  title: Hanto API
  version: 1.0.0
  description: >-
    Use Hanto to enrich one personal email into a professional profile match
    when Hanto can return a trusted result.
servers:
  - url: https://api.hanto.ai
security:
  - bearerAuth: []
paths:
  /api/v1/person/enrich:
    post:
      tags:
        - Personal email enrichment
      summary: Enrich a person
      description: Submit one personal email. Hanto returns a final synchronous result.
      operationId: enrichPerson
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrichPersonRequest'
            examples:
              personalEmail:
                summary: Personal email
                value:
                  email: person@gmail.com
      responses:
        '200':
          description: Hanto found a professional profile match.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichPersonFoundResponse'
              examples:
                found:
                  summary: Found
                  value:
                    lookup_id: lookup_2F0knGH5CSqVAveuPlyCelx1
                    status: found
                    profile:
                      linkedin_url: https://www.linkedin.com/in/person
        '400':
          description: The request body or email input is invalid or unsupported.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/InvalidRequestError'
                  - $ref: '#/components/schemas/InvalidEmailError'
                  - $ref: '#/components/schemas/UnsupportedEmailError'
              examples:
                invalidRequest:
                  summary: Invalid request
                  value:
                    error: invalid_request
                invalidEmail:
                  summary: Invalid email
                  value:
                    error: invalid_email
                unsupportedEmail:
                  summary: Unsupported email
                  value:
                    error: unsupported_email
        '401':
          description: The bearer API key is missing, invalid, or revoked.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedError'
              examples:
                unauthorized:
                  summary: Unauthorized
                  value:
                    error: unauthorized
        '402':
          description: The workspace cannot accept another lookup at this time.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientCreditsError'
              examples:
                insufficientCredits:
                  summary: Insufficient credits
                  value:
                    error: insufficient_credits
        '404':
          description: Hanto completed the lookup and could not return a match.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrichPersonNotFoundResponse'
              examples:
                notFound:
                  summary: Not found
                  value:
                    lookup_id: lookup_XbVW9yUdTzakGWNmZheBHvuV
                    status: not_found
        '429':
          description: The workspace exceeded the public API burst limit.
          headers:
            RateLimit-Limit:
              description: Maximum requests in the current window.
              schema:
                type: integer
                example: 500
            RateLimit-Remaining:
              description: Remaining requests in the current window.
              schema:
                type: integer
                example: 0
            RateLimit-Reset:
              description: Time when the current window resets.
              schema:
                type: integer
            Retry-After:
              description: Minimum time to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitedError'
              examples:
                rateLimited:
                  summary: Rate limited
                  value:
                    error: rate_limited
        '500':
          description: Hanto encountered a temporary service failure.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServerError'
              examples:
                serverError:
                  summary: Server error
                  value:
                    error: server_error
        '502':
          description: Hanto could not complete resolver work for this request.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LookupError'
              examples:
                lookupError:
                  summary: Lookup error
                  value:
                    error: lookup_error
        '503':
          description: >-
            Hanto could not verify the rate-limit state, so the request was not
            executed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitUnavailableError'
              examples:
                rateLimitUnavailable:
                  summary: Rate limit unavailable
                  value:
                    error: rate_limit_unavailable
components:
  schemas:
    EnrichPersonRequest:
      type: object
      additionalProperties: false
      required:
        - email
      properties:
        email:
          type: string
          format: email
          description: Personal email address to enrich.
          example: person@gmail.com
    EnrichPersonFoundResponse:
      type: object
      additionalProperties: false
      required:
        - lookup_id
        - status
        - profile
      properties:
        lookup_id:
          type: string
          description: Unique lookup identifier.
          example: lookup_2F0knGH5CSqVAveuPlyCelx1
        status:
          type: string
          enum:
            - found
        profile:
          type: object
          additionalProperties: false
          required:
            - linkedin_url
          properties:
            linkedin_url:
              type: string
              format: uri
              description: LinkedIn profile URL for the matched person.
              example: https://www.linkedin.com/in/person
    InvalidRequestError:
      $ref: '#/components/schemas/ErrorInvalidRequest'
    InvalidEmailError:
      $ref: '#/components/schemas/ErrorInvalidEmail'
    UnsupportedEmailError:
      $ref: '#/components/schemas/ErrorUnsupportedEmail'
    UnauthorizedError:
      $ref: '#/components/schemas/ErrorUnauthorized'
    InsufficientCreditsError:
      $ref: '#/components/schemas/ErrorInsufficientCredits'
    EnrichPersonNotFoundResponse:
      type: object
      additionalProperties: false
      required:
        - lookup_id
        - status
      properties:
        lookup_id:
          type: string
          description: Unique lookup identifier.
          example: lookup_XbVW9yUdTzakGWNmZheBHvuV
        status:
          type: string
          enum:
            - not_found
    RateLimitedError:
      $ref: '#/components/schemas/ErrorRateLimited'
    ServerError:
      $ref: '#/components/schemas/ErrorServer'
    LookupError:
      $ref: '#/components/schemas/ErrorLookup'
    RateLimitUnavailableError:
      $ref: '#/components/schemas/ErrorRateLimitUnavailable'
    ErrorInvalidRequest:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: string
          enum:
            - invalid_request
    ErrorInvalidEmail:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: string
          enum:
            - invalid_email
    ErrorUnsupportedEmail:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: string
          enum:
            - unsupported_email
    ErrorUnauthorized:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: string
          enum:
            - unauthorized
    ErrorInsufficientCredits:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: string
          enum:
            - insufficient_credits
    ErrorRateLimited:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: string
          enum:
            - rate_limited
    ErrorServer:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: string
          enum:
            - server_error
    ErrorLookup:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: string
          enum:
            - lookup_error
    ErrorRateLimitUnavailable:
      type: object
      additionalProperties: false
      required:
        - error
      properties:
        error:
          type: string
          enum:
            - rate_limit_unavailable
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key
      description: >-
        Bearer authentication header of the form `Bearer <token>`, where
        `<token>` is your Hanto API key.

````