> ## 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.

# Full Business Enrichment

> One call returns everything for a contact: work profile, device IDs, hashed emails. Send a hashed or plaintext email, an IP address, or a batch of up to 1,000 values.

Single mode: provide a pre-computed `md5`, a plaintext `email`, or an IPv4 or IPv6 `ip_address` with an optional `user_agent`. USA IPs only! Choose exactly one identifier family. The response combines the business profile (same field names as `/hem_to_business_profile`) with the contact's mobile advertising IDs. `work_email_confirmed` is always plaintext, with `work_email_confirmed_md5` and `work_email_confirmed_sha256` alongside so callers have all three forms; no personal email data is returned. The `maid` key is always present (`null` when no MAID data is found), and when the profile lookup misses but MAID data exists the full profile shape is still returned with `null` values. A match returns HTTP 200 `{ result: {...} }`; a miss returns HTTP 404 `{ result: {} }`.

Batch mode: send an `md5s` or `ips` array (max 1,000). MD5s are lowercased and de-duplicated; equivalent IP spellings are de-duplicated while preserving the first input. One malformed MD5 fails the whole request with HTTP 400 before any lookups run. Otherwise the response is always HTTP 200 with `results`, `match_count`, `credits_charged`, and `credits_exhausted`. Every matched result returns `md5`; IP batch results also echo `ip_address`. Inputs with no data are omitted. Processing stops once the account's remaining credits are exhausted (`credits_exhausted: true`).

**Billing:** the full configured per-record cost when both the business profile and MAID data match; 1 credit when only one of the two sources resolves (partial data); 0 credits for a miss (single-mode 404, or omitted from batch `results`). IP-sourced matches add 1 credit (full 4, partial 2 at the default price). Request errors (4xx) are not billed.



## OpenAPI

````yaml POST /api/v1/identity/business
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/identity/business:
    post:
      tags:
        - Identity
      summary: Full Business Enrichment
      description: >-
        One call returns everything for a contact: work profile, device IDs,
        hashed emails. Send a hashed or plaintext email, an IP address, or a
        batch of up to 1,000 values.


        Single mode: provide a pre-computed `md5`, a plaintext `email`, or an
        IPv4 or IPv6 `ip_address` with an optional `user_agent`. USA IPs only!
        Choose exactly one identifier family. The response combines the business
        profile (same field names as `/hem_to_business_profile`) with the
        contact's mobile advertising IDs. `work_email_confirmed` is always
        plaintext, with `work_email_confirmed_md5` and
        `work_email_confirmed_sha256` alongside so callers have all three forms;
        no personal email data is returned. The `maid` key is always present
        (`null` when no MAID data is found), and when the profile lookup misses
        but MAID data exists the full profile shape is still returned with
        `null` values. A match returns HTTP 200 `{ result: {...} }`; a miss
        returns HTTP 404 `{ result: {} }`.


        Batch mode: send an `md5s` or `ips` array (max 1,000). MD5s are
        lowercased and de-duplicated; equivalent IP spellings are de-duplicated
        while preserving the first input. One malformed MD5 fails the whole
        request with HTTP 400 before any lookups run. Otherwise the response is
        always HTTP 200 with `results`, `match_count`, `credits_charged`, and
        `credits_exhausted`. Every matched result returns `md5`; IP batch
        results also echo `ip_address`. Inputs with no data are omitted.
        Processing stops once the account's remaining credits are exhausted
        (`credits_exhausted: true`).


        **Billing:** the full configured per-record cost when both the business
        profile and MAID data match; 1 credit when only one of the two sources
        resolves (partial data); 0 credits for a miss (single-mode 404, or
        omitted from batch `results`). IP-sourced matches add 1 credit (full 4,
        partial 2 at the default price). Request errors (4xx) are not billed.
      operationId: identityBusiness
      parameters: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: >-
                Choose exactly one single or batch identifier mode:
                `md5`/`email`, `md5s`, `ip_address`, or `ips`.
              properties:
                md5:
                  type: string
                  pattern: ^[a-fA-F0-9]{32}$
                  description: MD5 hash of the lowercased, trimmed email address.
                  example: 5d41402abc4b2a76b9719d911017c592
                email:
                  type: string
                  format: email
                  description: Plaintext email address. Alternative to `md5`.
                  example: alice@example.com
                md5s:
                  type: array
                  minItems: 1
                  maxItems: 1000
                  items:
                    type: string
                    pattern: ^[a-fA-F0-9]{32}$
                  description: >-
                    Batch lookup: up to 1,000 MD5 hashes. When present, the
                    request is processed in batch mode. Cannot be combined with
                    IP inputs.
                ip_address:
                  type: string
                  description: >-
                    Single IPv4 or IPv6 address. USA IPs only! Cannot be
                    combined with email inputs.
                  example: 203.0.113.42
                user_agent:
                  type: string
                  description: Optional browser user agent for a single IP lookup.
                ips:
                  type: array
                  minItems: 1
                  maxItems: 1000
                  items:
                    type: string
                  description: >-
                    Batch lookup of up to 1,000 IPv4 or IPv6 addresses. USA IPs
                    only! Cannot be combined with email inputs.
              oneOf:
                - anyOf:
                    - required:
                        - md5
                    - required:
                        - email
                  not:
                    anyOf:
                      - required:
                          - md5s
                      - required:
                          - ip_address
                      - required:
                          - ips
                - required:
                    - md5s
                  not:
                    anyOf:
                      - required:
                          - md5
                      - required:
                          - email
                      - required:
                          - ip_address
                      - required:
                          - ips
                - required:
                    - ip_address
                  not:
                    anyOf:
                      - required:
                          - md5
                      - required:
                          - email
                      - required:
                          - md5s
                      - required:
                          - ips
                - required:
                    - ips
                  not:
                    anyOf:
                      - required:
                          - md5
                      - required:
                          - email
                      - required:
                          - md5s
                      - required:
                          - ip_address
            examples:
              single:
                summary: Single lookup
                value:
                  md5: 5d41402abc4b2a76b9719d911017c592
              batch:
                summary: Batch lookup (up to 1,000)
                value:
                  md5s:
                    - 5d41402abc4b2a76b9719d911017c592
                    - 098f6bcd4621d373cade4e832627b4f6
              ip:
                summary: Single IP lookup
                value:
                  ip_address: 203.0.113.42
                  user_agent: Mozilla/5.0
              ip_batch:
                summary: Batch IP lookup (up to 1,000)
                value:
                  ips:
                    - 203.0.113.42
                    - 2001:db8::42
        required: true
      responses:
        '200':
          description: Business identity found
          content:
            application/json:
              schema:
                oneOf:
                  - type: object
                    required:
                      - result
                    description: >-
                      Single-lookup response (`md5`, `email`, or `ip_address`
                      input).
                    properties:
                      result:
                        type: object
                        description: >-
                          Business profile plus MAID data for the matched
                          contact. Additional fields may appear as new data
                          becomes available.
                        additionalProperties: true
                        properties:
                          md5:
                            type: string
                            nullable: true
                            description: >-
                              Matched HEM. For IP input, this is the winning
                              resolved HEM.
                            example: 5d41402abc4b2a76b9719d911017c592
                          first_name:
                            type: string
                            nullable: true
                            example: Alice
                          last_name:
                            type: string
                            nullable: true
                            example: Smith
                          title:
                            type: string
                            nullable: true
                            example: VP of Marketing
                          seniority:
                            type: string
                            nullable: true
                            example: vp
                          functional_area:
                            type: string
                            nullable: true
                            example: Marketing
                          current_industry:
                            type: string
                            nullable: true
                            example: Computer Software
                          country:
                            type: string
                            nullable: true
                            example: United States
                          linkedinurl:
                            type: string
                            nullable: true
                            description: LinkedIn public profile URL.
                            example: https://www.linkedin.com/in/alice-123
                          current_company:
                            type: string
                            nullable: true
                            description: Company name (title-cased).
                            example: Acme
                          current_company_linkedinurl:
                            type: string
                            nullable: true
                            example: https://www.linkedin.com/company/acme
                          current_company_url:
                            type: string
                            nullable: true
                            example: https://acme.com
                          company_employee_count:
                            type: string
                            nullable: true
                            example: '120'
                          company_employee_range:
                            type: string
                            nullable: true
                            example: 51-200
                          company_revenue_range:
                            type: string
                            nullable: true
                            example: $10M-$50M
                          work_email_confirmed:
                            type: string
                            nullable: true
                            description: >-
                              Confirmed work email, always returned in
                              plaintext.
                            example: alice@acme.com
                          work_email_confirmed_md5:
                            type: string
                            nullable: true
                            description: MD5 hash of `work_email_confirmed`.
                            example: 4eb2eb38f58a848b48244e95b1e88bff
                          work_email_confirmed_sha256:
                            type: string
                            nullable: true
                            description: SHA-256 hash of `work_email_confirmed`.
                            example: >-
                              973dfe463ec85785f5f95af5ba3906eedb2d931c24e69824a89ea65dba4e813b
                          work_email_confirmed_status:
                            type: string
                            description: >-
                              Date the work email was last confirmed. Only
                              present when a confirmation date is known.
                            example: '2025-11-03'
                          maid:
                            type: array
                            nullable: true
                            description: >-
                              Mobile advertising IDs linked to the contact,
                              mirroring the `/hem_to_maid` response shape. The
                              key is always present; `null` when no MAID data
                              was found.
                            items:
                              $ref: '#/components/schemas/Maid'
                  - type: object
                    required:
                      - results
                      - match_count
                      - credits_charged
                      - credits_exhausted
                    description: Batch response (`md5s` or `ips` input). Always HTTP 200.
                    properties:
                      results:
                        type: array
                        description: >-
                          One entry per matched input identifier, in input
                          order. Unmatched inputs are omitted.
                        items:
                          oneOf:
                            - type: object
                              required:
                                - md5
                              not:
                                required:
                                  - ip_address
                              additionalProperties: true
                              properties:
                                md5:
                                  type: string
                                  description: Input MD5 correlation key.
                                first_name:
                                  type: string
                                  nullable: true
                                  example: Alice
                                last_name:
                                  type: string
                                  nullable: true
                                  example: Smith
                                title:
                                  type: string
                                  nullable: true
                                  example: VP of Marketing
                                seniority:
                                  type: string
                                  nullable: true
                                  example: vp
                                functional_area:
                                  type: string
                                  nullable: true
                                  example: Marketing
                                current_industry:
                                  type: string
                                  nullable: true
                                  example: Computer Software
                                country:
                                  type: string
                                  nullable: true
                                  example: United States
                                linkedinurl:
                                  type: string
                                  nullable: true
                                  description: LinkedIn public profile URL.
                                  example: https://www.linkedin.com/in/alice-123
                                current_company:
                                  type: string
                                  nullable: true
                                  description: Company name (title-cased).
                                  example: Acme
                                current_company_linkedinurl:
                                  type: string
                                  nullable: true
                                  example: https://www.linkedin.com/company/acme
                                current_company_url:
                                  type: string
                                  nullable: true
                                  example: https://acme.com
                                company_employee_count:
                                  type: string
                                  nullable: true
                                  example: '120'
                                company_employee_range:
                                  type: string
                                  nullable: true
                                  example: 51-200
                                company_revenue_range:
                                  type: string
                                  nullable: true
                                  example: $10M-$50M
                                work_email_confirmed:
                                  type: string
                                  nullable: true
                                  description: >-
                                    Confirmed work email, always returned in
                                    plaintext.
                                  example: alice@acme.com
                                work_email_confirmed_md5:
                                  type: string
                                  nullable: true
                                  description: MD5 hash of `work_email_confirmed`.
                                  example: 4eb2eb38f58a848b48244e95b1e88bff
                                work_email_confirmed_sha256:
                                  type: string
                                  nullable: true
                                  description: SHA-256 hash of `work_email_confirmed`.
                                  example: >-
                                    973dfe463ec85785f5f95af5ba3906eedb2d931c24e69824a89ea65dba4e813b
                                work_email_confirmed_status:
                                  type: string
                                  description: >-
                                    Date the work email was last confirmed. Only
                                    present when a confirmation date is known.
                                  example: '2025-11-03'
                                maid:
                                  type: array
                                  nullable: true
                                  description: >-
                                    Mobile advertising IDs linked to the
                                    contact, mirroring the `/hem_to_maid`
                                    response shape. The key is always present;
                                    `null` when no MAID data was found.
                                  items:
                                    $ref: '#/components/schemas/Maid'
                            - type: object
                              required:
                                - md5
                                - ip_address
                              additionalProperties: true
                              properties:
                                md5:
                                  type: string
                                  nullable: true
                                  description: >-
                                    Matched HEM. For IP input, this is the
                                    winning resolved HEM.
                                  example: 5d41402abc4b2a76b9719d911017c592
                                first_name:
                                  type: string
                                  nullable: true
                                  example: Alice
                                last_name:
                                  type: string
                                  nullable: true
                                  example: Smith
                                title:
                                  type: string
                                  nullable: true
                                  example: VP of Marketing
                                seniority:
                                  type: string
                                  nullable: true
                                  example: vp
                                functional_area:
                                  type: string
                                  nullable: true
                                  example: Marketing
                                current_industry:
                                  type: string
                                  nullable: true
                                  example: Computer Software
                                country:
                                  type: string
                                  nullable: true
                                  example: United States
                                linkedinurl:
                                  type: string
                                  nullable: true
                                  description: LinkedIn public profile URL.
                                  example: https://www.linkedin.com/in/alice-123
                                current_company:
                                  type: string
                                  nullable: true
                                  description: Company name (title-cased).
                                  example: Acme
                                current_company_linkedinurl:
                                  type: string
                                  nullable: true
                                  example: https://www.linkedin.com/company/acme
                                current_company_url:
                                  type: string
                                  nullable: true
                                  example: https://acme.com
                                company_employee_count:
                                  type: string
                                  nullable: true
                                  example: '120'
                                company_employee_range:
                                  type: string
                                  nullable: true
                                  example: 51-200
                                company_revenue_range:
                                  type: string
                                  nullable: true
                                  example: $10M-$50M
                                work_email_confirmed:
                                  type: string
                                  nullable: true
                                  description: >-
                                    Confirmed work email, always returned in
                                    plaintext.
                                  example: alice@acme.com
                                work_email_confirmed_md5:
                                  type: string
                                  nullable: true
                                  description: MD5 hash of `work_email_confirmed`.
                                  example: 4eb2eb38f58a848b48244e95b1e88bff
                                work_email_confirmed_sha256:
                                  type: string
                                  nullable: true
                                  description: SHA-256 hash of `work_email_confirmed`.
                                  example: >-
                                    973dfe463ec85785f5f95af5ba3906eedb2d931c24e69824a89ea65dba4e813b
                                work_email_confirmed_status:
                                  type: string
                                  description: >-
                                    Date the work email was last confirmed. Only
                                    present when a confirmation date is known.
                                  example: '2025-11-03'
                                maid:
                                  type: array
                                  nullable: true
                                  description: >-
                                    Mobile advertising IDs linked to the
                                    contact, mirroring the `/hem_to_maid`
                                    response shape. The key is always present;
                                    `null` when no MAID data was found.
                                  items:
                                    $ref: '#/components/schemas/Maid'
                                ip_address:
                                  type: string
                                  description: Input IP correlation key.
                      match_count:
                        type: integer
                        description: >-
                          Number of input identifiers that matched and were
                          billed.
                        example: 2
                      credits_charged:
                        type: number
                        description: Total credits charged for this batch.
                        example: 4
                      credits_exhausted:
                        type: boolean
                        description: >-
                          True when processing stopped early because the account
                          ran out of credits; remaining inputs were not
                          processed.
                        example: false
        '400':
          description: Invalid request
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                    enum:
                      - missing md5_or_email
                      - invalid md5
                      - missing md5s
                      - too_many_md5s
                      - missing ip_address
                      - invalid ip_address
                      - missing ips
                      - too_many_ips
                      - invalid ip
                      - invalid ips
                      - conflicting_identifier_inputs
                      - unexpected connection error
                      - unexpected error
                    description: >-
                      `missing md5_or_email`: single mode, neither `md5` nor
                      `email` was provided. `invalid md5`: an MD5 is not a
                      32-character hex digest (in batch mode `invalid` and
                      `index` identify the offending value). `missing md5s`:
                      batch mode with an empty `md5s` array. `too_many_md5s`:
                      more than 1,000 MD5s (see `max`). `unexpected connection
                      error` / `unexpected error`: temporary error; safe to
                      retry.
                  max:
                    type: integer
                    description: >-
                      Present on `too_many_md5s` or `too_many_ips`: the batch
                      size limit.
                    example: 1000
                  invalid:
                    type: string
                    description: >-
                      Present on batch `invalid md5` or `invalid ip`: the
                      offending input value.
                    example: not-an-md5
                  index:
                    type: integer
                    description: >-
                      Present on batch `invalid md5` or `invalid ip`: zero-based
                      position.
                    example: 3
                  conflicting:
                    type: array
                    items:
                      type: string
                    description: >-
                      Identifier fields supplied together when
                      `conflicting_identifier_inputs` is returned.
        '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 data found (not billed)
          content:
            application/json:
              schema:
                type: object
                required:
                  - result
                properties:
                  result:
                    type: object
                    description: >-
                      Empty object; neither business profile nor MAID data
                      matched the supplied identifier.
                    maxProperties: 0
      security:
        - api_key: []
components:
  schemas:
    Maid:
      type: object
      description: >-
        Mobile advertising ID (MAID) entry. Either field can be null when only
        one side of the pair is known.
      properties:
        device_id:
          type: string
          nullable: true
          example: 6D92078A-8246-4BA4-AE5B-76104861E7DC
        device_type:
          type: string
          nullable: true
          example: idfa
    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.