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

# IP → Hashed Email

> Resolve an IP (and browser details) into the visitor's hashed email.

Provide an IPv4 or IPv6 `ip_address` (optionally with the visitor's `user_agent`). We use our proprietary identity resolution technology to derive and return up to 3 matches ordered by descending confidence score; set `include_sha256` to also return each match's SHA-256 hashed email.

**Billing:** 1 credit per successful lookup (HTTP 200), regardless of how many matches are returned. Misses (404) and request errors (4xx) are not billed.



## OpenAPI

````yaml POST /api/v1/ip_to_hem
openapi: 3.0.1
info:
  title: Retention API
  version: v1
  description: Retention.com identity & data resolution APIs.
servers:
  - url: https://api.rb2b.com
security: []
tags:
  - name: Identity
    description: >-
      Core Identity. Resolve a hashed email (or batch) into a shaped person
      profile.
paths:
  /api/v1/ip_to_hem:
    post:
      tags:
        - IP
      summary: IP → Hashed Email
      description: >-
        Resolve an IP (and browser details) into the visitor's hashed email.


        Provide an IPv4 or IPv6 `ip_address` (optionally with the visitor's
        `user_agent`). We use our proprietary identity resolution technology to
        derive and return up to 3 matches ordered by descending confidence
        score; set `include_sha256` to also return each match's SHA-256 hashed
        email.


        **Billing:** 1 credit per successful lookup (HTTP 200), regardless of
        how many matches are returned. Misses (404) and request errors (4xx) are
        not billed.
      operationId: ipToHem
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - ip_address
              properties:
                ip_address:
                  type: string
                  description: IPv4 or IPv6 address of the visitor.
                  example: 203.0.113.42
                user_agent:
                  type: string
                  description: >-
                    Visitor's browser User-Agent. Optional; improves match
                    confidence when provided.
                  example: >-
                    Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)
                    AppleWebKit/537.36
                include_sha256:
                  type: boolean
                  default: false
                  description: Also include each match's SHA-256 hashed email as `sha256`.
        required: true
      responses:
        '200':
          description: Matches found (1 credit charged)
          content:
            application/json:
              schema:
                type: object
                required:
                  - results
                properties:
                  results:
                    type: array
                    description: Up to 3 hashed-email matches, ordered by descending score.
                    items:
                      type: object
                      required:
                        - md5
                        - score
                      properties:
                        md5:
                          type: string
                          pattern: ^[a-fA-F0-9]{32}$
                          description: MD5 hash of the visitor's email address.
                          example: 5d41402abc4b2a76b9719d911017c592
                        sha256:
                          type: string
                          pattern: ^[a-fA-F0-9]{64}$
                          description: >-
                            SHA-256 hash of the visitor's email address. Present
                            only when `include_sha256` was requested.
                          example: >-
                            2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
                        score:
                          type: number
                          description: Match confidence score; higher is more confident.
                          example: 0.9
        '400':
          description: Missing or invalid IP
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                    enum:
                      - missing ip_address
                      - invalid ip_address
                      - unexpected error
                    description: >-
                      `missing ip_address`: no `ip_address` was provided.
                      `invalid ip_address`: the value is not a valid IPv4 or
                      IPv6 address. `unexpected error`: temporary error; safe to
                      retry.
        '401':
          description: Missing, malformed, or unknown API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthError'
        '402':
          description: Insufficient credits
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InsufficientCreditsError'
        '403':
          description: Service not enabled for this API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ServiceDisabledError'
        '404':
          description: No results (not billed)
          content:
            application/json:
              schema:
                type: object
                required:
                  - results
                properties:
                  results:
                    type: array
                    description: Always empty; no hashed emails matched the supplied IP.
                    items: {}
                    maxItems: 0
      security:
        - api_key: []
components:
  schemas:
    AuthError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          enum:
            - missing_api_key
            - invalid_api_key_format
            - invalid_api_key
          description: >-
            `missing_api_key`: no key supplied. `invalid_api_key_format`: key
            does not match the expected format. `invalid_api_key`: key does not
            belong to any account.
    InsufficientCreditsError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          enum:
            - insufficient_api_credits
        required:
          type: string
          description: Credits needed for this request.
          example: '1.0'
        remaining:
          type: string
          description: Credits currently remaining on the account.
          example: '0.0'
    ServiceDisabledError:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          enum:
            - service_unavailable_for_key
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        Per-account API key. Also accepted as `Api-Key` or `Authorization:
        Bearer <key>`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.