opentrust.in/docs

API docs

A small JSON API. Base URL https://opentrust.in/api/v1. Create your key from your dashboard.

Libraries

Small, dependency-free clients that wrap this API with typed errors, so you can be up and running in a few lines. They're open source and live in our public repository.

Ruby · gem
gem install opentrust

client = OpenTrust::Client.new
client.lookup("9876543210").reported?
Node.js · npm
npm install opentrust

const ot = new OpenTrust();
(await ot.lookup("9876543210")).reported

Both read OPENTRUST_API_KEY from the environment. See all libraries and integrations, including the Shopify and WooCommerce plugins on the way. Want a library for another language? Tell us.

Authentication

Send your key as a bearer token on every request. Keep it secret and revoke it from the dashboard if it leaks. Requests are limited to 120 per minute per key.

header
Authorization: Bearer ot_live_xxxxxxxxxxxxxxxxxxxxxxxx

Send a hash instead of a number

You don't have to send us customers' phone numbers. Wherever an endpoint takes phone, it also takes phone_sha256: the SHA-256 of the number. We match on it without receiving the number, and a number and its hash find each other.

The format has to be exact. A hash that was computed from a differently written number simply finds nothing, which looks like a clean customer. So:

  1. Keep the digits. Drop a leading 91 (12 digits) or 0 (11 digits). What is left must be 10 digits starting with 6, 7, 8 or 9.
  2. Put +91 in front: +919876543210.
  3. SHA-256 of that text, as 64 lowercase hex characters.
  4. Send phone_length with it: the length of the text you hashed. It is always 13 (+91 and ten digits).

Why the length? It is a guard against the quiet mistake. A hash of 9876543210 (10), 09876543210 (11) or 919876543210 (12) looks fine but never matches anything. If you send any other length we refuse the request with a message that says what probably went wrong, and it costs no check. Compute it from the text you actually hashed (len(number)); copying a constant defeats the point.

test vector
+919876543210  →  f3a47ce5ce3d4ca8ad15225a245b2759022f79489f5c62719b8c9490f7aab90e

# check it yourself
printf '%s' '+919876543210' | shasum -a 256

The libraries do all of this for you: OpenTrust::Client.new(hash_numbers: true) in Ruby, new OpenTrust({ hashNumbers: true }) in Node. Both also export the hashing helper, and both are tested against the same test vectors as this server.

  • Check a number: { "phone_sha256": "…", "phone_length": 13 }. The result has phone_sha256 instead of phone_last4, since we never saw the number.
  • Check many: { "phone_sha256s": ["…", "…"], "phone_length": 13 } instead of phones, with one phone_length for the whole list. Results come back in order.
  • Share an experience: phone_sha256 with phone_length and phone_last4 (the last four digits, for display). We then hold the hash and the last four digits only. The same fields work in a batch.
  • Withdraw: phone_sha256 and phone_length.
  • Send phone or phone_sha256, never both.

Test your hashing. POST /phone_hash/check with a test number and your hash returns what we compute and whether yours matches. It costs no checks. It takes the number, so never use it with a customer's.

request
curl https://opentrust.in/api/v1/phone_hash/check \
  -H "Authorization: Bearer $OPENTRUST_API_KEY" \
  -d phone="98765 43210" \
  -d phone_sha256=f3a47ce5ce3d4ca8ad15225a245b2759022f79489f5c62719b8c9490f7aab90e

What a hash does and doesn't do. There are only about four billion Indian mobile numbers, so anyone willing to try them all can reverse a plain hash, including us. Sending hashes limits what is transmitted and stored (and what could leak from a log or a database); it does not make a number anonymous, and we treat a hash as personal data.

POST /lookups

Check one number. Uses 1 check from your allowance. Any common format works: 98765 43210, 09876543210 or +919876543210.

curl -X POST https://opentrust.in/api/v1/lookups \
  -H "Authorization: Bearer $OPENTRUST_KEY" \
  -d phone=9876543210
# gem install opentrust
require "opentrust"

client = OpenTrust::Client.new # reads OPENTRUST_API_KEY
result = client.lookup("9876543210")
result.reported?     # true / false
result.reports       # what other merchants noted
result.notice        # keep this in front of anyone who sees the result
// npm install opentrust
import { OpenTrust } from "opentrust";

const ot = new OpenTrust(); // reads OPENTRUST_API_KEY
const result = await ot.lookup("9876543210");
result.reported;     // true / false
result.reports;      // what other merchants noted
result.notice;       // keep this in front of anyone who sees the result
const res = await fetch("https://opentrust.in/api/v1/lookups", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENTRUST_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ phone: "9876543210" }),
});
const result = await res.json();
import os, requests

res = requests.post(
    "https://opentrust.in/api/v1/lookups",
    headers={"Authorization": f"Bearer {os.environ['OPENTRUST_KEY']}"},
    json={"phone": "9876543210"},
)
result = res.json()
$ch = curl_init("https://opentrust.in/api/v1/lookups");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("OPENTRUST_KEY"),
                         "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode(["phone" => "9876543210"]),
  CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
require "net/http"
require "json"

uri = URI("https://opentrust.in/api/v1/lookups")
req = Net::HTTP::Post.new(uri, "Authorization" => "Bearer #{ENV['OPENTRUST_KEY']}",
                               "Content-Type" => "application/json")
req.body = { phone: "9876543210" }.to_json
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
result = JSON.parse(res.body)

Or send a hash, so we never receive the number. The number is hashed on your side and we match on the hash (how, and what a hash does and doesn't do). The format is exact, so you also send phone_length, the length of the text you hashed, which is always 13. The libraries do all of it for you, and the other examples spell it out.

# phone_sha256 is the SHA-256 of "+91" and the ten digits, as lowercase hex
NUMBER='+919876543210'
HASH=$(printf '%s' "$NUMBER" | shasum -a 256 | cut -d' ' -f1)
curl -X POST https://opentrust.in/api/v1/lookups \
  -H "Authorization: Bearer $OPENTRUST_KEY" \
  -d phone_sha256=$HASH \
  -d phone_length=${#NUMBER}   # 13: the length of the text you hashed
client = OpenTrust::Client.new(hash_numbers: true)
result = client.lookup("98765 43210") # sends only the hash and its length, never the number
const ot = new OpenTrust({ hashNumbers: true });
const result = await ot.lookup("98765 43210"); // sends only the hash and its length, never the number
import { createHash } from "node:crypto";

function normalize(raw) {
  let d = String(raw).replace(/\D/g, "");
  if (d.length === 12 && d.startsWith("91")) d = d.slice(2);
  if (d.length === 11 && d.startsWith("0")) d = d.slice(1);
  if (!/^[6-9]\d{9}$/.test(d)) throw new Error("not an Indian mobile number");
  return "+91" + d;
}

const number = normalize("98765 43210");   // "+919876543210"
const res = await fetch("https://opentrust.in/api/v1/lookups", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.OPENTRUST_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    phone_sha256: createHash("sha256").update(number).digest("hex"),
    phone_length: number.length,   // 13: the length of the text you hashed
  }),
});
const result = await res.json();
import hashlib, os, re, requests

def normalize(raw):
    d = re.sub(r"\D", "", raw)
    if len(d) == 12 and d.startswith("91"): d = d[2:]
    if len(d) == 11 and d.startswith("0"): d = d[1:]
    if not re.fullmatch(r"[6-9]\d{9}", d): raise ValueError("not an Indian mobile number")
    return "+91" + d

number = normalize("98765 43210")   # "+919876543210"
res = requests.post(
    "https://opentrust.in/api/v1/lookups",
    headers={"Authorization": f"Bearer {os.environ['OPENTRUST_KEY']}"},
    json={
        "phone_sha256": hashlib.sha256(number.encode()).hexdigest(),
        "phone_length": len(number),   # 13: the length of the text you hashed
    },
)
result = res.json()
<?php
function normalize($raw) {
    $d = preg_replace('/\D/', '', $raw);
    if (strlen($d) === 12 && strpos($d, '91') === 0) $d = substr($d, 2);
    if (strlen($d) === 11 && $d[0] === '0') $d = substr($d, 1);
    if (!preg_match('/^[6-9]\d{9}$/', $d)) throw new InvalidArgumentException('not an Indian mobile number');
    return '+91' . $d;
}

$number = normalize("98765 43210");   // "+919876543210"
$ch = curl_init("https://opentrust.in/api/v1/lookups");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => ["Authorization: Bearer " . getenv("OPENTRUST_KEY"),
                         "Content-Type: application/json"],
  CURLOPT_POSTFIELDS => json_encode([
    "phone_sha256" => hash("sha256", $number),
    "phone_length" => strlen($number),   // 13: the length of the text you hashed
  ]),
  CURLOPT_RETURNTRANSFER => true,
]);
$result = json_decode(curl_exec($ch), true);
require "digest"
require "net/http"
require "json"

def normalize(raw)
  d = raw.to_s.gsub(/\D/, "")
  d = d[2..-1] if d.length == 12 && d.start_with?("91")
  d = d[1..-1] if d.length == 11 && d.start_with?("0")
  raise ArgumentError, "not an Indian mobile number" unless d.match?(/\A[6-9]\d{9}\z/)
  "+91#{d}"
end

number = normalize("98765 43210")   # "+919876543210"
uri = URI("https://opentrust.in/api/v1/lookups")
req = Net::HTTP::Post.new(uri, "Authorization" => "Bearer #{ENV['OPENTRUST_KEY']}",
                               "Content-Type" => "application/json")
req.body = { phone_sha256: Digest::SHA256.hexdigest(number),
             phone_length: number.length }.to_json   # 13: the length of the text you hashed
res = Net::HTTP.start(uri.hostname, uri.port, use_ssl: true) { |h| h.request(req) }
result = JSON.parse(res.body)

Response 200

response.json
{
  "phone_last4": "3210",
  "reported": true,
  "report_count": 1,
  "own_report": false,
  "reports": [
    {
      "reason_code": "chargeback",
      "reason": "Disputed a payment (chargeback)",
      "notes": "Disputed 3 card payments",
      "incident_at": "2026-09-28",
      "confirmed_by": null,
      "reported_at": "2026-10-01",
      "reporter_verified": true
    }
  ],
  "notice": "Reports are unverified observations shared by individual merchants. …",
  "checks_remaining": 99999
}
  • reports: [] and report_count: 0 mean no merchant has reported the number.
  • report_count and reports only hold reports from other merchants. own_report tells you whether you have shared this number yourself, so your own report is never counted as a signal from someone else.
  • incident_at is the date the merchant says it happened (or null); reported_at is the day it was shared. Recent incidents usually matter more than old ones.
  • You never get the full number back, only phone_last4, and never who reported. If you sent a hash, phone_sha256 comes back instead of phone_last4, since we never saw the number.
  • notice is included in every response. Please keep it in front of anyone who sees a result.

POST /lookups/batch

Check up to 100 numbers. Uses one check per number, all or nothing: if you don't have enough checks, none are used and you get a 402.

Prefer not to send the numbers? Send phone_sha256s (a list of SHA-256 hashes) and one phone_length instead of phones. See Send a hash.

curl
curl -X POST https://opentrust.in/api/v1/lookups/batch \
  -H "Authorization: Bearer $OPENTRUST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phones": ["9876543210", "9000000001"]}'

Response 200

response.json
{
  "results": [
    {
      "phone_last4": "3210",
      "reported": true,
      "report_count": 1,
      "own_report": false,
      "reports": [
        "…"
      ]
    },
    {
      "phone_last4": "0001",
      "reported": false,
      "report_count": 0,
      "own_report": false,
      "reports": [

      ]
    }
  ],
  "notice": "…",
  "checks_remaining": 99998
}

POST /reports

Share an experience with a number. Optional, and it doesn't change your allowance. Only share what your own business directly experienced, as plain facts.

Prefer not to send the number? Send phone_sha256, phone_length and phone_last4 (the last four digits) instead of phone. See Send a hash.

curl
curl -X POST https://opentrust.in/api/v1/reports \
  -H "Authorization: Bearer $OPENTRUST_KEY" \
  -d phone=9876543210 \
  -d reason_code=chargeback \
  -d incident_at=2026-03-14 \
  -d "notes=Disputed 3 card payments in March"
  • reason_code is one of the reason codes below.
  • notes is optional, up to 500 characters, except for other, which needs at least 10. No names, accusations, emails, links or phone numbers.
  • incident_at is optional: when it happened, as a date (2026-03-14) or an ISO 8601 time. It can't be in the future.
  • confirmed_by is optional: bank, payment_gateway or law_enforcement, only if they told you the activity was confirmed. Other merchants see it as "the reporter says it was confirmed by…"; OpenTrust does not verify it.
  • evidence_ref is optional and private (up to 100 characters, sent with confirmed_by): a complaint or ticket number we can ask you about if a report is questioned. It is never shown to other merchants.
  • Each merchant can share one report per number. If you withdraw yours (below) you can share it again.
  • Share the number of the person who did it: the number they used to order, pay, call or message you. Never the number of someone who may be a victim, for example the real owner of an account that someone else misused.

Response 201

response.json
{
  "id": 42,
  "phone_last4": "3210",
  "status": "recorded"
}

POST /reports/batch

Share up to 100 experiences at once. Free, like a single report. Each report is handled on its own: a bad row never stops the others, and the answer is always 200 with one result per report, in the same order. Meant for loading history and for platforms that report in bulk.

Each report may use phone_sha256, phone_length and phone_last4 instead of phone. See Send a hash.

curl
curl -X POST https://opentrust.in/api/v1/reports/batch \
  -H "Authorization: Bearer $OPENTRUST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reports": [
        {"phone": "9876543210", "reason_code": "chargeback", "notes": "Card payment disputed on 2 orders", "incident_at": "2026-08-14"},
        {"phone": "9812345678", "reason_code": "fake_order"}
      ]}'

Response 200

response.json
{
  "results": [
    {
      "index": 0,
      "status": "recorded",
      "id": 42,
      "phone_last4": "3210"
    },
    {
      "index": 1,
      "status": "duplicate",
      "error": {
        "code": "duplicate_report",
        "message": "you have already reported this number"
      }
    }
  ],
  "summary": {
    "recorded": 1,
    "duplicate": 1,
    "invalid": 0
  }
}
  • status is recorded, duplicate (you already shared this number; treat as done) or invalid (see error.code; fix the row, don't retry it unchanged).
  • A request with no reports, more than 100, or something other than a list is refused with 422 invalid_reports.
  • It counts as one request toward the rate limit, so 100 reports a call is far quicker than 100 single calls.

DELETE /reports

Withdraw your own report for a number. Use it when you got it wrong or the situation was resolved. It stops appearing in other merchants' results straight away and is deleted after 90 days. You can only withdraw reports you shared yourself.

You can send phone_sha256 and phone_length instead of phone.

curl
curl -X DELETE https://opentrust.in/api/v1/reports \
  -H "Authorization: Bearer $OPENTRUST_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone": "9876543210"}'

You can also send the number in the URL: DELETE /reports?phone=9876543210.

Response 200

response.json
{
  "phone_last4": "3210",
  "status": "withdrawn"
}

If you have no active report for that number you get 404 report_not_found, which you can treat as success when cleaning up.

GET /reason_codes

The reason codes. A code describes what your business observed, not a conclusion about the person. Codes never change meaning or disappear, and new ones are only added when merchants would act differently on them. Free to call: fetch the list instead of hard-coding it.

Choosing a code

  • Only what you saw yourself. A confirmed outcome, such as a dispute, a refusal or a call you received, is a report. A hunch, a risk score or "looks suspicious" is not.
  • Report the person who did it. Use the number they used to order, pay, call or message you, never the number of someone who may be a victim.
  • Pick the most specific code that fits, and use the most serious one if several apply. There is one report per number, so mention the rest in the note.
  • Use other last, with a note. If the same thing keeps showing up there, tell us and it may get its own code.
  • You can withdraw a report whenever your view changes.

Orders and returns

cod_refusal Refused a cash-on-delivery order
The customer refused or did not accept a cash-on-delivery order at the door.
Use it when The customer placed a cash-on-delivery order and refused or didn't accept it at delivery, especially more than once.
Not when The item was wrong or damaged, or the delivery was badly late. That is an ordinary refusal, not a pattern of the customer.
fake_order Placed an order that appeared fake
An order that looked like it was placed with no intention to buy, for example with false details.
Use it when The order details were clearly false (a made-up name, address or contact) or the order was placed with no intention of receiving it.
Not when The customer only changed their mind. If they refused at the door, use cod_refusal.
return_abuse Repeated return or refund abuse
Repeated returns or refund requests that looked like abuse of the return policy.
Use it when The same customer repeatedly returned items or claimed refunds against your policy, for example saying 'not received' for delivered orders, or returning used or swapped items.
Not when A single return or dispute, however annoying, or a genuine defect.

Payments

chargeback Disputed a payment (chargeback)
The customer disputed or reversed a payment (a card chargeback, or a UPI or bank dispute), or the payment gateway reported it as fraudulent.
Use it when A payment was disputed or reversed after you delivered or credited (a card chargeback, or a UPI or bank dispute), or your payment gateway reported it as fraudulent.
Not when You agreed to an ordinary refund, or you only suspect fraud and no dispute has been raised.
fake_payment_proof Shared payment proof that didn't check out
A payment screenshot or reference that turned out not to match a real payment.
Use it when A screenshot, UTR or reference the customer gave as proof of payment didn't match any real payment.
Not when The payment was real but later reversed. Use chargeback.
third_party_payment_fraud Paid from someone else's card, bank account or wallet
A payment or deposit came from a card, bank account or wallet in another person's name, and the account holder did not own or authorise it.
Use it when You confirmed the payment or deposit came from a card, bank account or wallet in another person's name, and the account holder did not own or authorise it.
Not when Someone paid with a relative's card with the holder's consent, or you only noticed a different name and haven't confirmed anything.

Accounts and identity

identity_fraud Used someone else's identity details
Someone used another person's name, documents or other identity details.
Use it when You confirmed someone used another person's name, documents or identity details to sign up, order or verify.
Not when The documents merely didn't match or couldn't be verified (use document_mismatch), or you don't know whose identity was used.
document_mismatch Submitted documents that didn't match
Documents submitted for verification (such as KYC) didn't match the account details or couldn't be verified.
Use it when Documents submitted for KYC or verification didn't match the account details, or couldn't be verified, after you checked.
Not when You confirmed they used someone else's identity (use identity_fraud), or the difference was a spelling variation you resolved.

Offers and programs

promo_abuse Abused offers, cashback or referrals
Abuse of offers, cashback, referral rewards, sign-up bonuses or wallet credits, including through multiple accounts.
Use it when A customer abused offers against their terms: several accounts to claim sign-up bonuses, referral rewards or cashback, or misused wallet credits or coupons.
Not when One legitimate use of an offer, or using several coupons the terms allow.

Impersonation and phone calls

otp_fraud Asked someone for an OTP
Someone asked a customer or a member of staff to share an OTP.
Use it when Someone phoned or messaged your customer or staff and asked them to share an OTP.
Not when An OTP your own system sent to a customer. Report the caller's number, never the customer's.
bank_impersonation Posed as a bank or financial institution
Someone claimed to be calling from a bank or other financial institution.
Use it when Someone claimed to be a bank or financial institution when contacting you or your customers.
Not when A genuine bank or payment partner you can verify.
merchant_impersonation Posed as our business or support
Someone claimed to represent the merchant's business or its customer support.
Use it when Someone claimed to be your business, delivery or support when contacting your customers or staff.
Not when A real member of your own team or a partner you have authorised.
phishing_link Sent a suspicious payment or login link
Someone sent a payment or login link that looked designed to collect money or credentials.
Use it when A link sent from this number led to a payment or login page that wasn't yours, or looked designed to collect money or credentials.
Not when An ordinary promotional or tracking link.
kyc_scam Posed as a KYC or verification agent
Someone claimed to be completing a KYC or account verification.
Use it when Someone said an account or wallet would be blocked unless a KYC or verification step was completed through them.
Not when A real KYC request that came from you or your partner.
refund_scam Made a suspicious refund request
A refund request that looked like a scam, for example asking for the money to go to a different account.
Use it when Someone contacted you about a refund nobody asked for, or asked for money to be sent back or refunded to a different account.
Not when A refund request you can tie to a real order.

Other

other Other
Something not covered above. A short factual note (at least 10 characters) is required.
Use it when Nothing above fits. Say what happened in a sentence of at least 10 characters. If the same thing keeps coming up, tell us and it may become a code.
Not when Anything that fits a code above, or anything you only suspect.

GET /me

See your checks. Free to call.

response.json
{
  "merchant": "Your Shop",
  "checks_remaining": 99998,
  "reports_submitted": 3
}

Running low? Write to [email protected] and we'll set a generous limit.

Errors

Every error has the same shape:

error.json
{
  "error": {
    "code": "no_checks_remaining",
    "message": "You have used all your checks. …"
  }
}
401invalid_api_keyMissing or invalid API key
402no_checks_remainingNo checks left. Write to us and we'll raise your limit
403merchant_not_approvedAccount isn't approved or is suspended
404report_not_foundYou have no active report for that number (withdrawing)
409duplicate_reportYou already shared this number
422invalid_phone / invalid_report / invalid_incident_at / invalid_reportsInvalid number, reason code, note, date or list
429rate_limitedOver 120 requests per minute

Using results responsibly

Reports are unverified observations shared by individual merchants. They are not a finding that anyone committed fraud. Use them as one input among others, not as the sole reason to refuse a customer.

  • Have a person review any decision that materially affects a customer.
  • Don't tell customers that OpenTrust is the reason for a decision.
  • Don't resell, republish or bulk-export results. See the Terms.
opentrust-intro.mp4