Registry: Quickstart | Omnifence API docs

This guide takes you from a registry key to a working sign-up check and your first report.

Prerequisites#

An active registry membership and a registry API key. See Membership.
Node.js 18 or later, or cURL.

1. Store your registry key

Keep the key out of your code. The examples read it from an environment variable.

Shell

export OMNIFENCE_REGISTRY_KEY="your_registry_key_here"

2. Add the hash function

Copy the reference implementation into your codebase as registry-hash.mjs. It exports registryDigest(email), which returns the value to send, or null when the value is not an email.

Confirm that it produces the published value:

JavaScript

import { registryDigest } from './registry-hash.mjs';

console.log(registryDigest('J.a.n.e.D.o.e+promo@gmail.com'));
// d6117306485ed0e50afab3ac871e98f81699151f30281527d63ff5f233656c69

3. Check a sign-up

Call the registry when a user creates an account, before you activate it.

Shell

curl -X POST https://api.omnifence.ai/api/v1/registry/check \
  -H "Authorization: Bearer $OMNIFENCE_REGISTRY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifiers": [
      { "type": "email", "sha256": "d6117306485ed0e50afab3ac871e98f81699151f30281527d63ff5f233656c69" }
    ],
    "context": "signup"
  }'

A user that no member reported returns:

JSON

{ "match": false, "signals": [], "normalisation_version": 1 }

4. Act on the result

On a match, apply your policy for each signal. Refuse on the match alone only when automated_refusal_permitted is true. See Act on a match for a complete sign-up handler.

5. Report a ban

When your team bans a user for a registry category, report the email hash with your own case reference.

Shell

curl -X POST https://api.omnifence.ai/api/v1/registry/entries \
  -H "Authorization: Bearer $OMNIFENCE_REGISTRY_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "identifier": { "type": "email", "sha256": "d6117306485ed0e50afab3ac871e98f81699151f30281527d63ff5f233656c69" },
    "category": "payment_fraud",
    "member_case_ref": "TS-48213",
    "attest_human_review": true
  }'

The API returns 201 Created with the new entry. Keep its entry_id with your case, so that you can revoke the report if you overturn the ban.

Prerequisites#

Next steps#