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.
gem install opentrust
client = OpenTrust::Client.new
client.lookup("9876543210").reported?npm install opentrust
const ot = new OpenTrust();
(await ot.lookup("9876543210")).reportedBoth 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.
Authorization: Bearer ot_live_xxxxxxxxxxxxxxxxxxxxxxxxSend 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:
- 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.
- Put +91 in front: +919876543210.
- SHA-256 of that text, as 64 lowercase hex characters.
- 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.
+919876543210 → f3a47ce5ce3d4ca8ad15225a245b2759022f79489f5c62719b8c9490f7aab90e
# check it yourself
printf '%s' '+919876543210' | shasum -a 256The 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.
curl https://opentrust.in/api/v1/phone_hash/check \
-H "Authorization: Bearer $OPENTRUST_API_KEY" \
-d phone="98765 43210" \
-d phone_sha256=f3a47ce5ce3d4ca8ad15225a245b2759022f79489f5c62719b8c9490f7aab90eWhat 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 resultconst 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 hashedclient = OpenTrust::Client.new(hash_numbers: true)
result = client.lookup("98765 43210") # sends only the hash and its length, never the numberconst ot = new OpenTrust({ hashNumbers: true });
const result = await ot.lookup("98765 43210"); // sends only the hash and its length, never the numberimport { 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
{
"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 -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
{
"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
}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 -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
{
"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.
{
"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": {
"code": "no_checks_remaining",
"message": "You have used all your checks. …"
}
}| 401 | invalid_api_key | Missing or invalid API key |
| 402 | no_checks_remaining | No checks left. Write to us and we'll raise your limit |
| 403 | merchant_not_approved | Account isn't approved or is suspended |
| 404 | report_not_found | You have no active report for that number (withdrawing) |
| 409 | duplicate_report | You already shared this number |
| 422 | invalid_phone / invalid_report / invalid_incident_at / invalid_reports | Invalid number, reason code, note, date or list |
| 429 | rate_limited | Over 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.