Hash-to-identifier lookup endpoint

1. How matching works

MineOS sends the hash and the identifier type (list type). 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

{
  "identifier_type": "email",
  "identifiers": [
    { "drop_id": "30er02673907", "hash": "b3d9...e1" },
    { "drop_id": "483910sm0y75", "hash": "77af...02" },
    { "drop_id": "11a2849og76y", "hash": "0c5e...9d" }
  ]
}

Field	Type	Description
`identifier_type`	string	One of `email`, `phone`, `ndz`, `maid`, `ctvid`, `vin` . Determines which normalization applies and which plain identifiers to expect in return.
`identifiers`	array<object>	The batch of identifiers to resolve. Each object contains a `hash` and its corresponding `drop_ip`
`drop_ip`	string	The unique DROP ID correlating to the hash, as downloaded from DROP
`hash`	string	The hashed identifier value

4. Response

Return one result object per input hash. Preserve order is not required — MineOS matches on drop_id and hash. Mine expects to receive results to all of the identifiers in the correlating request.

{
  "identifier_type": "email",
  "results": [
    {
      "drop_id": "30er02673907",
      "hash": "b3d9...e1",
      "status": "found",
      "action": "delete",
      "identifiers": {
        // return any of the following supported types
        "email": "[email protected]",
        "phone": "4155550137",
        "first_name": "jane",
	"last_name": "doe",
        "dob": "19850314",
	"zip": "94105",
        "maid": "e1b2c3d49f8e7d6c5b4a0102030405f6",
        "ctvid": "vizio7c4d2e9a1b",
        "vin": "5yj3e1ea7kf000316"
      }
    },
    {
      "drop_id": "483910sm0y75",
      "hash": "77af...02",
      "status": "not_found"
    },
    {
      "drop_id": "11a2849og76y",
      "hash": "7btf...72",
      "status": "error"
    }
  ]
}

Field	Type	Description
`hash`	string	The input hash this result corresponds to.
`status`	string	`found`, `not_found`or `error` `status` is `error` when you are unable to complete a single `drop_id` lookup. Note that if you were able to complete a single `drop_id` lookup and haven't found a match, you should report `status` is `not_found.`
`action`	string	Required when `status` is `found`; omit otherwise. Valid values: `delete`, `exempt` or `opt_out`
`identifiers`	object	Required when `status` is `found`; omit otherwise. Its required to return all the plain identifiers belonging to the data subject, regardless of the specific list type. All identifiers should be returned in the 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.