Success response
A successful response has a HTTP status code of 200, and always contains a response JSON that looks like this:
{
"id": "d4bhu2b1",
"url": "https://app.usedanger.com/app/events/d4bhu2b1",
"external_id": null,
"outcome": "block",
"rules": [
{
"id": "anonymous_browsing",
"type": "smart",
"name": "Anonymous browsing",
"action": "block"
},
{
"id": "b2jcp4l2",
"type": "custom",
"name": "Problem email domain",
"action": "block"
},
...
],
"device": {
"success": true,
"integrity_ip_match": true,
"integrity_unique": true,
"integrity_unexpired": true,
"fingerprint": "9a78264e64e22174240b666e8408b4b9",
"ja3": "40b666e848b4b99a78264e6e22179742",
"ip": "204.158.96.40",
"ipv6": "2001:db8:3333:4444:5555:6666:7777:8888",
"bot": false,
"browser": "Safari",
"private_browsing": true,
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_1_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.1.1 Mobile/15E148 Safari/604.1",
"ua_os_family": "iOS",
"ua_os_version": "17.1.1",
"ua_device_type": "mobile",
"ua_device_brand": "Apple",
"ua_device_family": "iPhone",
"ua_device_model": "iPhone",
"country_name": "United States",
"country_code": "US",
"timezone": "America/Chicago"
},
"address": {
"success": true,
"valid": true,
"in_country": true,
"postal_code_match": true,
"address1": "35 Lodgeville Rd",
"address2": "",
"city": "Minneapolis",
"state": "Minnesota",
"country_name": "United States",
"country_code": "US",
"postal_code": "55480",
"latitude": 44.9255,
"longitude": -93.3034
},
"email": {
"success": true,
"valid": true,
"email": "[email protected]",
"local_part": "dan",
"normalized_email": "[email protected]",
"normalized_local_part": "dan",
"domain": "example.com",
"domain_tld": "com",
"domain_tld_high_risk": false,
"domain_registrar": "MarkMonitor, Inc.",
"domain_age": 10359,
"digits_count": 0,
"name_match": true,
"free": true,
"disposable": false,
"business": false,
"breaches": {
"success": true,
"found_count": 10,
"found": [
"CafePress",
"PDL",
"Lastfm",
...
]
},
"registered": {
"total_count": 20,
"success_count": 16,
"success_ratio": 0.8,
"found_count": 4,
"found_ratio": 0.25,
"apple": true,
"disney": false,
"spotify": false,
...
}
},
"ip": {
"success": true,
"in_country": true,
"ip": "204.158.96.40",
"isp": "Comcast Cable Communications LLC",
"organization": "Comcast Cable Communications LLC",
"carrier": "Verizon",
"type": "business",
"city": "Minneapolis",
"state": "Minnesota",
"country_name": "United States",
"country_code": "US",
"postal_code": "55400",
"timezone": "America/Chicago",
"latitude": 40.9255,
"longitude": -89.3034,
"vpn": true,
"relay": false,
"proxy": false,
"tor": false,
"hosting": false,
"threat": false,
"bogon": false
},
"linked": {
"events_all_matched": 3,
"events_all_possible": 1,
"events_all_total": 4,
"events_allowed_matched": 1,
"events_allowed_possible": 0,
"events_allowed_total": 1,
"events_first_seen": "2024-01-01 19:05:46.017311"
},
"phone": {
"success": true,
"valid": true,
"in_country": true,
"phone": "+12126647665",
"phone_international": "+1 212-664-7665",
"phone_national": "(212) 664-7665",
"carrier": "T-Mobile",
"carrier_high_risk": false,
"country_name": "United States",
"country_code": "US",
"type": "mobile",
"reachable": true
},
"proximity": {
"device_ip_timezone_match": true,
"address_ip_distance": 27.25,
"address_ip_country_match": true,
"address_phone_country_match": true
}
}
The default response fields will reflect the information provided in the request. For example, email data will always be present if an email property is provided in the request. You can tailor the fields provided in the response using the filtering feature. This is useful to reduce ingress bandwidth for your application where a part of the response is not useful to you.
Using an SDK?
An SDK interprets the response into a set of actionable outputs (such as allow (allow the event, true/false), country, timezone, email_valid, etc.), as well as providing access to the full result where you need it. Learn about SDKs and libraries if you'd find this helpful.
outcome property
The outcome after applying rules to the event:
allow: The event either matches an allow rule, the email/IP is allowlisted, or no rules matched at all.allow_review: Same asallow, except the event will be placed into the event review queue in the dashboard.block: The event matched a block rule.block_review: Same asblock, except the event will be placed into the event review queue in the dashboard.review: Only a review rule matched. The event will be placed into the event review queue in the dashboard.
Your application should normally block the user only when the outcome is block or block_review. Note that allow rules take precedence over block. This means that if at least one allow rule matches, the outcome will be to allow the event.
Using an SDK?
An SDK provides an allow (true/false), use this to decide whether to allow the event to continue.
rules property
Each item within rules describes a rule that the event matched. The type is either smart (smart rule), custom (custom rule), or allowlist (IP or email found on allowlist).
You can use the ID to check for a particular rule match in your application. The IDs for custom rules are shown in the UI, and you'll find the IDs for smart rules in our guide.
Read the API reference for the rules object.
device, address, email, ip, linked, phone, and proximity properties
Each of the lookup types have some standard properties...
success is true or false to indicate whether the lookup itself was successful. Expect this to be false where there is a timeout, an internal error, or problem at Danger's side.
valid will be true or false to indicate whether the provided value (i.e. the email address or phone number), is real. I.e. they are in the correct format, and basic checks pass.
email, ip, phone, etc. holds the provided value (or best match in the case of address) coerced into a standardised and consistent format. This may be useful as a clean value for storing in your database.
There are other type-specific properties that contain the result of the lookup. Often there is a property that will provide a definitive answer as to true validity (i.e. reachable for phone numbers).
To review the properties available for each type of lookup, please see the API reference section.
Other fields
The id is the event's own ID, with url providing a quick way to access the event in the dashboard.
The external_id reflects an optional ID supplied in the request, such as the application's customer ID (more about this later).