> ## 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. # Personal Identity > B2C consumer identity: personal hashed emails, device IDs, location, and last-seen activity. Accepts hashed or plaintext email and IP address inputs. 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 carries the consumer's personal hashed emails (`hems`), mobile advertising IDs (`maids`), `personal_emails`, coarse `location`, and `last_seen_at` activity. `personal_emails` are MD5-hashed unless you send a plaintext `email`. 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; email fields are always MD5-hashed in batch results. Processing stops once the account's remaining credits are exhausted (`credits_exhausted: true`). **Billing:** the full configured per-record cost when both the 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`). `last_seen_at` and `location` are supplemental and never affect billing. 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/consumer 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/consumer: post: tags: - Identity summary: Personal Identity description: >- B2C consumer identity: personal hashed emails, device IDs, location, and last-seen activity. Accepts hashed or plaintext email and IP address inputs. 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 carries the consumer's personal hashed emails (`hems`), mobile advertising IDs (`maids`), `personal_emails`, coarse `location`, and `last_seen_at` activity. `personal_emails` are MD5-hashed unless you send a plaintext `email`. 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; email fields are always MD5-hashed in batch results. Processing stops once the account's remaining credits are exhausted (`credits_exhausted: true`). **Billing:** the full configured per-record cost when both the 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`). `last_seen_at` and `location` are supplemental and never affect billing. IP-sourced matches add 1 credit (full 4, partial 2 at the default price). Request errors (4xx) are not billed. operationId: identityConsumer 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. When present, email fields in the response are returned in plaintext. 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: Consumer 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: Consumer identity signals for the matched person. properties: md5: type: string nullable: true description: >- Matched HEM. For IP input, this is the winning resolved HEM. example: 5d41402abc4b2a76b9719d911017c592 ip_address: type: string description: >- Input IP correlation key on IP batch results. Omitted for email input. example: 203.0.113.42 hems: type: array description: >- Hashed email variants for every known personal email (personal emails only; no work emails on this endpoint). items: $ref: '#/components/schemas/Hem' maids: type: array description: >- Mobile advertising IDs linked to the consumer. Always present; empty array when no MAID data was found. items: $ref: '#/components/schemas/Maid' personal_emails: type: array items: type: string description: >- Personal email addresses. MD5-hashed unless you send a plaintext `email`; batch results are always MD5-hashed. location: type: object description: >- Coarse consumer location. V1: `country` is always "US" and `city`/`state` are null (no consumer-geo source yet). properties: city: type: string nullable: true example: null state: type: string nullable: true example: null country: type: string example: US last_seen_at: type: string nullable: true description: >- ISO 8601 timestamp of the consumer's most recent observed online activity. Supplemental; null when no activity is known; never affects billing. example: '2026-05-28T14:03:11Z' - 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. Email fields are always MD5-hashed. items: oneOf: - type: object required: - md5 not: required: - ip_address properties: md5: type: string nullable: true description: >- Matched HEM. For IP input, this is the winning resolved HEM. example: 5d41402abc4b2a76b9719d911017c592 hems: type: array description: >- Hashed email variants for every known personal email (personal emails only; no work emails on this endpoint). items: $ref: '#/components/schemas/Hem' maids: type: array description: >- Mobile advertising IDs linked to the consumer. Always present; empty array when no MAID data was found. items: $ref: '#/components/schemas/Maid' personal_emails: type: array items: type: string description: >- Personal email addresses. MD5-hashed unless you send a plaintext `email`; batch results are always MD5-hashed. location: type: object description: >- Coarse consumer location. V1: `country` is always "US" and `city`/`state` are null (no consumer-geo source yet). properties: city: type: string nullable: true example: null state: type: string nullable: true example: null country: type: string example: US last_seen_at: type: string nullable: true description: >- ISO 8601 timestamp of the consumer's most recent observed online activity. Supplemental; null when no activity is known; never affects billing. example: '2026-05-28T14:03:11Z' - type: object required: - md5 - ip_address properties: md5: type: string nullable: true description: >- Matched HEM. For IP input, this is the winning resolved HEM. example: 5d41402abc4b2a76b9719d911017c592 ip_address: type: string description: >- Input IP correlation key on IP batch results. Omitted for email input. example: 203.0.113.42 hems: type: array description: >- Hashed email variants for every known personal email (personal emails only; no work emails on this endpoint). items: $ref: '#/components/schemas/Hem' maids: type: array description: >- Mobile advertising IDs linked to the consumer. Always present; empty array when no MAID data was found. items: $ref: '#/components/schemas/Maid' personal_emails: type: array items: type: string description: >- Personal email addresses. MD5-hashed unless you send a plaintext `email`; batch results are always MD5-hashed. location: type: object description: >- Coarse consumer location. V1: `country` is always "US" and `city`/`state` are null (no consumer-geo source yet). properties: city: type: string nullable: true example: null state: type: string nullable: true example: null country: type: string example: US last_seen_at: type: string nullable: true description: >- ISO 8601 timestamp of the consumer's most recent observed online activity. Supplemental; null when no activity is known; never affects billing. example: '2026-05-28T14:03:11Z' 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 profile nor MAID data matched the supplied identifier. maxProperties: 0 security: - api_key: [] components: schemas: Hem: type: object description: Hashed email (HEM) pair for the same underlying address. properties: md5: type: string example: 5d41402abc4b2a76b9719d911017c592 sha256: type: string example: 2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824 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 `. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.