API documentation
One call. A verdict you can route on.
Signet scores an email address, phone number or IP address for signup and order fraud. Each call returns a verdict (allow, review or block), a risk score from 0 to 1, and the named signals behind it.
Every check runs through two layers:
- Free rules. Syntax, typo domains, role and throwaway patterns, a disposable-domain registry synced daily, reserved and Tor IP ranges, phone numbering plans. A check rejected here costs nothing.
- Deep check. Live DNS deliverability plus Signet's network reputation: fraud reports and flags from other merchants, and how often the same value was checked in the last 24 hours. A check that reaches this layer costs 1 credit.
Base URL for every endpoint:
https://puresignet.com/v1
Quickstart
Send the value you want to check. The type is detected automatically.
curl https://puresignet.com/v1/validate \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": "jane@company.com"}'
const res = await fetch("https://puresignet.com/v1/validate", {
method: "POST",
headers: {
"X-API-Key": process.env.SIGNET_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ input: "jane@company.com" }),
});
const result = await res.json();
if (!res.ok) throw new Error(`${result.code}: ${result.error}`);
if (result.verdict === "block") rejectSignup();
else if (result.verdict === "review") askForExtraVerification();
else createAccount();
import os, requests
res = requests.post(
"https://puresignet.com/v1/validate",
headers={"X-API-Key": os.environ["SIGNET_API_KEY"]},
json={"input": "jane@company.com"},
timeout=10,
)
result = res.json()
res.raise_for_status()
if result["verdict"] == "block":
reject_signup()
elif result["verdict"] == "review":
ask_for_extra_verification()
else:
create_account()
$ch = curl_init("https://puresignet.com/v1/validate");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"X-API-Key: " . getenv("SIGNET_API_KEY"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode(["input" => "jane@company.com"]),
]);
$result = json_decode(curl_exec($ch), true);
if ($result["verdict"] === "block") { rejectSignup(); }
The response:
{
"input": "jane@company.com",
"type": "email",
"normalized": "jane@company.com",
"valid": true,
"verdict": "allow",
"risk_score": 0,
"confidence": 0.88,
"fraud_indicators": [],
"free_provider": false,
"network": {
"merchants_seen": 0,
"merchants_flagged": 0,
"fraud_reports": 0,
"velocity_24h": 0
},
"layer": "deep_network",
"credits_used": 1,
"cached": false,
"response_time_ms": 142,
"credits_remaining": 99
}Prefer clicking to typing? The playground runs the same calls with your key.
Authentication
Send your API key in the X-API-Key header on every request. Keys look like ak_live_ followed by 32 hexadecimal characters.
- Create keys in your dashboard, which you sign in to with a link sent to your email. A new key is shown once; Signet stores only a hash of it and cannot show it again.
- Your plan sets how many keys you can have at once: 1 on the trial and Starter, 3 on Professional, 10 on Scale. Use separate keys for production, staging and each app, so one can be cut off without touching the others. All of an account's keys share its balance and its per-minute limit.
- Call the API from your server. Never put the key in browser or mobile app code, where anyone can read it.
- If a key leaks, replace it in the dashboard: the old key stops working at once and a new one takes its place. Revoke a key you no longer use.
Validate
Scores one email address, phone number or IP address.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
input | string | yes | The value to check. Up to 320 characters. |
type | string | no | email, phone or ip. Leave it out to auto-detect. Send it when you know it, so a mistyped email is judged as an email. |
country | string | no | Two-letter country code such as IN. Used to read phone numbers written without a +, e.g. 9820034571. |
live | boolean | no | Ask for a live check. See Live checks. |
Phone numbers work best in international format with a leading + and country code, for example +919820034571. If your customers type local numbers, send country with them. IPv4 and IPv6 are both supported.
What you get back for each type
| Type | Enrichment |
|---|---|
| Deliverability of the domain, disposable and typo detection with a suggested fix, whether it is a consumer mailbox. | |
| Phone | Country, line type (mobile, landline, voip, toll_free, premium_rate), international format, and whether the number sits in a range the country has issued. |
| IP | The network that owns the address, its AS number, where that network is registered, and whether it is a hosting provider rather than a home or mobile connection. |
The response is described under Response fields.
Live checks
A normal check works from rules, DNS and network reputation. A live check goes one step further and asks the source directly. Send "live": true:
| Type | What is asked | You get | Extra cost |
|---|---|---|---|
| The mail server: does this exact mailbox exist? | mailbox: deliverable, undeliverable or catch_all | +1 credit | |
| Phone | The mobile network: is this number in service right now? | line_status: connected, absent or not_in_service, plus carrier and ported | +2 credits |
curl https://puresignet.com/v1/validate \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": "+919820034571", "live": true}'- The extra credits are charged only when the source answers. Each result carries
"live": trueif it did. If it could not be reached, you get the normal verdict at the normal 1 credit and"live": false. - A live check is skipped, and costs nothing extra, when the free rules or DNS already settled the answer.
- Live checks take longer, sometimes a few seconds. Use them where the decision matters: before shipping a cash-on-delivery order, before paying out, before sending an expensive campaign.
- Availability. Live checks are being switched on gradually. Until they are on for your account,
"live": trueis accepted and simply returns"live": false.
VPN, proxy and Tor detection for IP addresses is part of every normal check and costs nothing extra.
Validate batch
Scores up to 100 values in one call.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
items | string[] | yes | 1 to 100 values, each up to 320 characters. |
type | string | no | Applies one type to every item. Leave it out to auto-detect each one. |
country | string | no | Two-letter country code used for phone numbers written without a +. |
curl https://puresignet.com/v1/validate/batch \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"items": ["jane@company.com", "x@mailinator.com", "8.8.8.8"]}'Response
{
"results": [ { "input": "jane@company.com", "verdict": "allow", "credits_used": 1, "…": "…" } ],
"summary": {
"total": 3, "valid": 2, "invalid": 1,
"allow": 2, "review": 0, "block": 1,
"credits_used": 2
},
"credits_remaining": 97
}resultsis in the same order asitems. Each entry has the same shape as a single validate response.- A value that appears more than once is charged once. Repeats come back with
"cached": trueand"credits_used": 0. - A batch is all-or-nothing. If your balance cannot cover it you get a
402and nothing is charged.
Feedback
Tell Signet how a signup or order actually turned out. Report a chargeback, a fake account or a returned cash-on-delivery order as fraud; report a confirmed good customer as legit. The next time anyone checks the same value, the verdict reflects it.
| Field | Type | Required | Description |
|---|---|---|---|
input | string | yes | The email, phone number or IP the outcome is about. |
outcome | string | yes | fraud or legit. |
type | string | no | Same as on validate. |
curl https://puresignet.com/v1/feedback \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"input": "fraudster@example.com", "outcome": "fraud"}'Each account counts as one vote per value, and sending a new outcome replaces your earlier one. A single report moves a value towards review; it takes reports from several independent merchants to block it.
Credits
curl https://puresignet.com/v1/credits -H "X-API-Key: YOUR_API_KEY"
{ "balance": 97, "api_key": "ak_live_9f3c…", "message": "Use /usage to see your usage history" }You rarely need this: every validate response already carries credits_remaining.
Usage
Totals for your key and your most recent checks. limit is 0 to 1000 (default 50); use 0 for totals only.
{
"email": "you@company.com",
"balance": 97,
"total_validations": 3,
"total_credits_used": 2,
"recent_usage": [
{
"id": 1042, "input": "j***@company.com", "type": "email",
"valid": true, "credits": 1, "layer": "deep_network",
"risk_score": 0, "created_at": "2026-11-14T05:31:09Z"
}
]
}Inputs in usage history are masked. See Data handling.
Test your key
Confirms a key works and returns the account it belongs to. Use it as a health check when you deploy.
curl -X POST https://puresignet.com/v1/test -H "X-API-Key: YOUR_API_KEY"
Response fields
| Field | Type | Description |
|---|---|---|
verdict | string | allow, review or block. The field to act on. See Verdicts. |
risk_score | number | 0 (no risk found) to 1 (certain). Combines every signal. |
valid | boolean | true when the value is well-formed and the risk score is under 0.5. |
confidence | number | 0 to 1. How decisive the evidence is. |
fraud_indicators | string[] | Names of the signals that fired. Empty when nothing did. See Fraud signals. |
network | object | null | Counts from other merchants: merchants_seen, merchants_flagged, fraud_reports, and velocity_24h (checks of this value in the last 24 hours). null when the input was malformed. |
type | string | email, phone or ip. |
input | string | What you sent. |
normalized | string | Cleaned form: lower-cased email, digits-only phone with +, trimmed IP. |
layer | string | Which layer settled it. Starts with local_ for the free rules; deep_network for the deep check. |
credits_used | integer | 0 or 1. |
credits_remaining | integer | Your balance after this call. |
cached | boolean | true for a repeated value inside a batch. |
response_time_ms | integer | Server processing time. |
suggestion | string | Emails only, when present: the likely intended address, e.g. john@gmail.com for john@gmial.com. |
free_provider | boolean | Emails only: a consumer mailbox such as Gmail or Outlook. |
country | string | Phones only: two-letter country code, e.g. IN. |
line_type | string | Phones only: mobile, landline, landline_or_mobile (countries such as the US that do not separate them), voip, toll_free, premium_rate or other. |
formatted | string | Phones only: the number in international format, e.g. +91 98200 34571. |
provider | string | IPs only: the organisation that operates the network. |
asn | integer | IPs only: the network's AS number. |
proxy_type | string | IPs only, when detected: vpn, tor or proxy. |
live | boolean | true when a live check answered for this item. |
domain_age_days | integer | Emails on a business domain, when known: days since the domain was registered (from public registry data). Not given for free mailbox providers such as Gmail. |
mailbox | string | Emails, live check only: deliverable, undeliverable or catch_all (the server accepts any name, so the inbox cannot be confirmed). |
line_status | string | Phones, live check only: connected, absent (switched off or out of coverage) or not_in_service. |
carrier, ported | string, boolean | Phones, live check only: the network the number is on now, and whether it moved there from another. |
network_country | string | IPs only: where the network block is registered. A strong hint about location, not a geolocation of the person. |
Verdicts
| Verdict | When | Suggested action |
|---|---|---|
| allow | Risk score under 0.3 and nothing invalid. | Let the signup or order through. |
| review | Risk score from 0.3 up to 0.7, or the value failed validation without being clearly fraudulent. | Add friction: email or OTP confirmation, prepaid instead of cash on delivery, or a manual look. Signet does not hold or review anything itself: your code decides, and treating review as allow is a valid choice. |
| block | Risk score 0.7 or higher, or the value is malformed. | Reject, and ask the person for a different email or number. |
If your tolerance differs, ignore the verdict and set your own thresholds on risk_score.
Credits & billing
| What happened | Credits |
|---|---|
| Rejected by the free rules (malformed, disposable, reserved range, obvious fake pattern) | 0 |
| Passed the free rules and went through the deep check, whatever the final verdict | 1 |
Live mailbox check that answered ("live": true on an email) | +1 |
Live number check that answered ("live": true on a phone) | +2 |
| Live check requested but the source did not answer | +0 |
| Repeated value inside one batch | 0 |
| Feedback, credits, usage and test calls | 0 |
| Any request that returns an error | 0 |
Trial and plans. Every account starts with a 7-day free trial that includes 100 deep checks; unused trial checks end with the trial. Each paid plan adds its monthly credits at the start of every billing period. On Professional unused credits stay usable for one extra month, on Scale for three; on Starter they end with the month. The oldest credits are always spent first.
Email, phone and IP checks all cost the same. When the balance reaches zero, deep checks return 402 insufficient_credits; values the free rules reject are still answered.
Fraud signals
These are the names that appear in fraud_indicators. Names ending in _invalid mean the value is malformed.
Network (any type)
reported_fraud_network | Other merchants reported this value as fraud. |
flagged_across_network | The value was judged risky at two or more other merchants. |
high_velocity | Checked unusually often in the last 24 hours. |
disposable_domain, disposable_pattern | A throwaway inbox provider. |
no_mx_records | The domain cannot receive email. |
new_domain | The email's domain was registered in the last 30 days (stronger under 7). Real businesses rarely sign up from a domain that is days old. domain_age_days gives the age. |
mailbox_not_found | Live check: the mail server says this mailbox does not exist. |
catch_all_domain | Live check: the server accepts mail for any name. Mild on its own. |
provider_typo | Looks like a mistyped major provider. A suggestion is included. |
provider_spoofing | A major provider's name embedded in another domain, e.g. gmail.com.example.tk. |
spam_trap_domain | A known spam-trap domain. |
fake_pattern, keyboard_walk, gibberish_local_part | The part before the @ looks made up: test, asdfgh, random characters. |
role_based_address | A shared mailbox such as admin@ or sales@. |
plus_alias, numeric_local_part, numeric_domain | Weak signals that add up with others. |
suspicious_tld_… | A top-level domain heavily used for abuse; the suffix names it. |
unicode_confusable_domain, unicode_confusable_local | Look-alike characters from another alphabet. |
free_email_provider | Informational. Carries almost no risk on its own. |
Phone
number_not_in_service | Live check: the mobile network says this number is not assigned to anyone. |
handset_unreachable | Live check: a real number, but the phone is off or out of coverage right now. Mild on its own. |
voip_number | An internet phone number: cheap to create in bulk and often unable to receive OTPs. |
non_personal_line | Toll-free, premium-rate or another kind of line that is not a person's own phone. |
landline | A fixed line. Mild on its own, but it cannot receive an SMS. |
unassigned_number_range | The right length for its country, but not in a range the country has issued. |
all_same_digit, sequential_digits, repeating_pairs, long_repeat, palindrome, repeating_last4 | Digit patterns people type when inventing a number. |
reserved_555_range, tollfree_555_combo, uk_fictional_range | Ranges reserved for fiction and testing. |
premium_rate_prefix, n11_service_code | Premium-rate or service numbers, not personal lines. |
invalid_area_code, unassigned_area_code, invalid_exchange_code | Not a number the North American plan can assign. |
length_for_country_mismatch, invalid_country_code, leading_zeros | Wrong shape for the country code given. |
IP address
tor_exit_node | A known Tor exit range. |
vpn_detected, proxy_detected, tor_network | The address is a known VPN server, open proxy or Tor exit. proxy_type says which. |
hijacked_network | The address is in a network Spamhaus lists as hijacked or run by criminals (the DROP list). Block. |
hosting_network | The address belongs to a cloud or hosting provider (including the ranges AWS, Google Cloud, Oracle and DigitalOcean publish). Real customers rarely browse from a server; bots, scrapers and VPN users do. |
datacenter_range, cdn_range | A hosting or CDN network, not a home or mobile connection. provider names it. |
private_rfc1918, loopback, link_local_apipa, carrier_grade_nat, unique_local, link_local | Not a public address. Usually means your server is passing its own or a proxy's IP instead of the visitor's. |
documentation_test_net, benchmarking, multicast, broadcast, reserved_future_use, this_network, unspecified_address | Reserved ranges that never belong to a real visitor. |
teredo_tunnel, 6to4_tunnel, nat64_well_known, discard_only | IPv6 tunnelling and special-purpose prefixes. |
Errors
Errors use standard HTTP status codes and always return JSON with a human-readable error and a stable code to branch on:
{ "error": "Not enough credits for this request.", "code": "insufficient_credits", "needed": 3, "balance": 1 }| Status | Code | Meaning |
|---|---|---|
| 400 | bad_input, bad_type, bad_items, too_many_items, bad_country, bad_live, bad_outcome, bad_json | Something in the request body is missing or wrong. The message says what. |
| 401 | invalid_api_key | The key is missing, malformed or unknown. |
| 402 | insufficient_credits | The balance cannot cover this request. Includes needed and balance. Nothing was charged. |
| 402 | trial_ended | The 7-day free trial is over. Choose a plan in the dashboard. |
| 402 | no_plan | The account has no active plan. |
| 403 | account_suspended | The account is paused. Contact support. |
| 405 | method_not_allowed | Wrong HTTP method for this endpoint. |
| 413 | payload_too_large | The request body is over 64 KB. |
| 422 | bad_input | Feedback only: the value is not a well-formed email, phone or IP. |
| 429 | rate_limited | Too many checks this minute for your plan. Wait for the number of seconds in the Retry-After header. |
| 500 | internal_error | Our fault. The body includes a request_id; send it to support and we can find the exact request. |
Limits
| Rate limit | Per account, by plan: 300 a minute during the trial, then 60 (Starter), 300 (Professional) or 1,200 (Scale). A batch counts one per item. Over the limit you get 429 with Retry-After. |
| Batch size | 100 items. |
| Input length | 320 characters per value. |
| Request body | 64 KB. |
Need more? Email hello@puresignet.com.
Data handling
- Masked logs. Signet does not store the values you check. Logs keep a masked form only, such as
j***@company.com,+919***78or203.0.*.*, and are deleted after 90 days. - Network reputation. To recognise a value seen at another merchant, Signet keeps a keyed one-way hash of it alongside the outcome. The hash cannot be turned back into the email, phone number or IP, and no merchant can see another merchant's data, only the counts in
network. - API keys. Stored as hashes. Nobody at Signet can read your key.
- Transport. HTTPS only.
Data sources
Alongside its own rules and the reports merchants send, Signet uses these free public sources. The lists are refreshed daily; domain ages are looked up when first needed and remembered.
| Source | Used for | Terms |
|---|---|---|
| disposable-email-domains | Throwaway email domains | CC0 / MIT |
| FakeFilter | Throwaway email domains | BSD-3-Clause, © 2022 7c |
| Tor Project exit list | Tor exit nodes | Public |
| Spamhaus DROP | Hijacked networks | Free, with credit to The Spamhaus Project |
| AWS, Google Cloud, Oracle Cloud, DigitalOcean | Cloud and hosting server ranges, as each provider publishes them | Published by each provider |
| RDAP (domain registries, via IANA) | When an email domain was registered | Public registry data |
| Team Cymru IP-to-ASN, Google and Cloudflare public DNS | Network owner and mail-server checks | Free public services |
| libphonenumber | Phone country, line type and numbering plans | Apache 2.0 |
Hijacked-network data: The Spamhaus Project, spamhaus.org/drop.
Integration tips
- Check at the moment of decision. Call validate when the signup form or checkout is submitted, on your server, before you create the account or accept the order.
- Pass the visitor's real IP. Behind a load balancer or CDN, read it from the forwarded-for header. A
private_rfc1918result means you sent your own. - Fail open. Set a timeout of a few seconds. If Signet is unreachable or returns a 5xx, let the signup through rather than blocking real customers.
- Use review. It is where most of the value is: confirm by OTP, or switch cash on delivery to prepaid, instead of a hard yes or no.
- Show the suggestion. When
suggestionis present, ask "Did you mean …?" on the form. It rescues real customers who mistyped. - Selling cash on delivery? Treat
voip_number,landlineandhosting_networkas reasons to ask for prepayment or an OTP before you ship. - Send feedback. Report chargebacks, fake accounts and returned orders. It is free and it improves your own future verdicts as well as the network's.
- Back off on 429. Honour
Retry-After, and prefer one batch call over many single calls for lists.
Roadmap
What we are working on, in order. Last updated November 2026. Nothing here is a promise of a date; if something on this list is what you are waiting for, tell us and it moves up.
| Status | What |
|---|---|
| Live | Email, phone and IP scoring; batch; fraud feedback and network reputation; phone country and line type; IP network owner, hosting, VPN, proxy and Tor detection. |
| Rolling out | Live checks: mailbox existence for emails, in-service status and current carrier for phones. |
| Next | Sign up and get a key instantly, without waiting for approval. Pay by card and top up credits yourself. |
| Later | Webhooks for verdict changes. A Shopify app for cash-on-delivery risk. A public status page. |