Hash-to-identifier lookup endpoint

1. How matching works

MineOS sends the hash, the identifier type (list type) and DROP list ID. To match, precompute the same hash over your own identifiers using the identical normalization and algorithm, and maintain a lookup from hash → plain identifiers.

The identifier normalization and hashing is defined below:

2. Endpoint

POST https://your-domain.example/drop/identifier-lookup
Authorization: Bearer <shared-secret>
Content-Type: application/json

Host the endpoint at any path you control; you will be able to register that URL and its credentials in the integration configuration. It should be reachable over TLS only.

3. Request

{
  "list_id": "drop-2026-07",
  "identifier_type": "email",
  "identifiers": [
    "b3d9...e1",
    "77af...02",
    "0c5e...9d"
  ]
}

Field	Type	Description
`list_id`	string	The DROP list these hashes belong to. Echo it back in the response.
`identifier_type`	string	One of `email`, `phone`, `ndz`, `maid`, `ctvid`, `vin` . Determines which normalization applies and which plain identifiers to expect in return.
`identifiers`	string[]	The batch of hashed identifiers to resolve.

4. Response

Return one result object per input hash. Preserve order is not required — MineOS matches on hash. Every list type requires different identifiers, we provide all the examples below:

{
  "list_id": "drop-2026-07",
  "identifier_type": "email",
  "results": [
    {
      "hash": "b3d9...e1",
      "status": "found",
      "identifiers": {
        "email": "[email protected]"
			}
    },
    {
      "hash": "77af...02",
      "status": "not_found"
    }
  ]
}

{
  "list_id": "drop-2026-07",
  "identifier_type": "phone",
  "results": [
    {
      "hash": "b3d9...e1",
      "status": "found",
      "identifiers": {
        "phone": "4155550137"
			}
    },
    {
      "hash": "77af...02",
      "status": "not_found"
    }
  ]
}

{
  "list_id": "drop-2026-07",
  "identifier_type": "ndz",
  "results": [
    {
      "hash": "b3d9...e1",
      "status": "found",
      "identifiers": {
        "first_name": "jane",
				"last_name": "doe",
        "dob": "19850314",
				"zip": "94105"

			}
    },
    {
      "hash": "77af...02",
      "status": "not_found"
    }
  ]
}

{
  "list_id": "drop-2026-07",
  "identifier_type": "maid",
  "results": [
    {
      "hash": "b3d9...e1",
      "status": "found",
      "identifiers": {
        "maid": "e1b2c3d49f8e7d6c5b4a0102030405f6"
			}
    },
    {
      "hash": "77af...02",
      "status": "not_found"
    }
  ]
}

{
  "list_id": "drop-2026-07",
  "identifier_type": "tvid",
  "results": [
    {
      "hash": "b3d9...e1",
      "status": "found",
      "identifiers": {
        "ctvid": "vizio7c4d2e9a1b",
        "first_name": "jane",
				"last_name": "doe"
			}
    },
    {
      "hash": "77af...02",
      "status": "not_found"
    }
  ]
}

{
  "list_id": "drop-2026-07",
  "identifier_type": "vin",
  "results": [
    {
      "hash": "b3d9...e1",
      "status": "found",
      "identifiers": {
        "first_name": "jane",
				"last_name": "doe",
        "vin": "5yj3e1ea7kf000316"
			}
    },
    {
      "hash": "77af...02",
      "status": "not_found"
    }
  ]
}

Field	Type	Description
`hash`	string	The input hash this result corresponds to.
`status`	string	`found` or `not_found`.
`identifiers`	object	The plain identifier. Required when `status` is `found`; omit otherwise. Return it in the same normalized form used for hashing.

Every input hash must appear exactly once in results. A hash with no matching record returns status: "not_found" — it is not omitted.

5. Batching and limits

MineOS sends identifiers in batches of up to 1000 hashes per request.
The call is idempotent: the same request may be retried and must return the same result.
Target a response within 30 seconds per batch. If a batch cannot be processed in time, return 429 so MineOS will backoff and retry.

6. Errors

Use standard HTTP status codes:

Code	Meaning
`200`	Success — body contains `results`.
`400`	Malformed request (missing field, unsupported `identifier_type`).
`401`	Authentication failed.
`429`	Rate limited — MineOS backs off and retries.
`5xx`	Transient server error — MineOS retries the batch.

For 4xx/5xx, return a small JSON body containing an error message:

{ "error": "unsupported_identifier_type", "message": "..." }

7. Security

This endpoint returns plain personal information, so treat it as a sensitive data path:

TLS only; reject non-HTTPS traffic.
Authenticate every request with an Authorization header.
Do not log plain identifiers or full request/response bodies. Log hashes and counts only.