User Trust API

The User Trust API is the foundational component of the Autheona platform. It allows you to programmatically verify the trustworthiness of a user, providing essential risk assessment data to secure your application and protect your operations.

By integrating the User Trust API, you can perform real-time checks to determine if a specific user account meets your platform safety standards. This API is critical for preventing fraud, ensuring policy compliance, and maintaining a secure environment for your customers.

Use the following cURL command to initiate a trust verification request:

curl -X POST "https://api.autheona.com/v1/intelligence" \
  -H "Content-Type: application/json" \
  -H "x-api-key: <access-token>" \
  -d '{
    "email_address": "<email-address>"
  }'

Endpoint

POST https://api.autheona.com/v1/intelligence

Authentication

To authenticate your request, include your access token in the header:

Request Body

Example Request

{
  "email_address": "user@example.com"
}

Using Fingerprint

To use fingerprint data, pass the value returned by the Fingerprint API:

{
  "email_address": "user@example.com",
  "fingerprint": "<ENCRYPTED-FINGERPRINT-DATA>"
}

Response

The API returns a JSON object containing the intelligence data for the provided email address.

Response Structure

{
  "action": "allow",
  "email": {
    "normalized": {
      "base": "string",
      "without_plus_addressing": "string",
      "without_dot_variations": "string",
      "without_punycode": "string",
      "without_typo_mismatch": "string"
    },
    "details": {
      "deliverability": "string",
      "local": {
        "fraud_pattern": "string",
        "mixed_script": "string",
        "has_fraud_pattern": "boolean",
        "has_mixed_script": "boolean",
        "has_dot_variation": "boolean",
        "has_plus_addressing": "boolean",
        "has_special_characters": "boolean",
        "has_numeric": "boolean",
        "has_hyphen": "boolean",
        "has_underscore": "boolean",
        "is_quoted": "boolean"
      },
      "domain": {
        "category": "string",
        "free_provider": "string",
        "punycode_value": "string",
        "has_valid_tld": "boolean",
        "has_website": "boolean",
        "has_punycode": "boolean",
        "has_typo_mismatch": "boolean",
        "is_ipv4": "boolean",
        "is_ipv6": "boolean",
        "is_only_numeric": "boolean",
        "is_single_label": "boolean",
        "subdomain": {
          "count": "integer",
          "has_hyphen": "boolean",
          "has_numeric": "boolean",
          "has_uuid": "boolean",
          "has_wildcard": "boolean"
        }
      }
    }
  },
  "ip": {
    "is_datacenter": "boolean",
    "is_tor": "boolean",
    "is_vpn": "boolean"
  },
  "velocity_by_email": {
    "items": [
      {
        "passed_email": "string",
        "created_at": "integer"
      }
    ],
    "count": "integer"
  },
  "velocity_by_ip": {
    "items": [
      {
        "ipv4_address": "string",
        "ipv6_address": "string",
        "created_at": "integer"
      }
    ],
    "count": "integer"
  }
}

Response Fields

Free Provider List

These are the values returned in the free_provider response field. They are grouped into two categories based on how commonly they are used:

Example Response

Without Fingerprint

{
  "action": "allow",
  "email": {
    "normalized": {
      "base": "john.doe@example.com",
      "without_plus_addressing": "john.doe@example.com",
      "without_dot_variations": null,
      "without_punycode": "john.doe@example.com",
      "without_typo_mismatch": "john.doe@example.com"
    },
    "details": {
      "deliverability": "deliverable",
      "local": {
        "fraud_pattern": null,
        "mixed_script": null,
        "has_fraud_pattern": false,
        "has_mixed_script": false,
        "has_dot_variation": true,
        "has_plus_addressing": false,
        "has_special_characters": false,
        "has_numeric": false,
        "has_hyphen": false,
        "has_underscore": false,
        "is_quoted": false
      },
      "domain": {
        "category": "business",
        "free_provider": null,
        "punycode_value": null,
        "has_valid_tld": true,
        "has_website": true,
        "has_punycode": false,
        "has_typo_mismatch": false,
        "is_ipv4": false,
        "is_ipv6": false,
        "is_only_numeric": false,
        "is_single_label": false,
        "subdomain": {
          "count": 0,
          "has_hyphen": false,
          "has_numeric": false,
          "has_uuid": false,
          "has_wildcard": false
        }
      }
    }
  },
  "ip": {
    "is_datacenter": null,
    "is_tor": null,
    "is_vpn": null
  },
  "velocity_by_email": {
    "items": [],
    "count": 0
  },
  "velocity_by_ip": {
    "items": [],
    "count": 0
  }
}

With Fingerprint

When a fingerprint is provided, IP-related fields are populated:

{
  "action": "allow",
  "email": {
    "normalized": {
      "base": "go1@012.net.il",
      "without_plus_addressing": null,
      "without_dot_variations": null,
      "without_punycode": null,
      "without_typo_mismatch": null
    },
    "details": {
      "deliverability": "unknown",
      "local": {
        "fraud_pattern": null,
        "mixed_script": null,
        "has_fraud_pattern": null,
        "has_mixed_script": null,
        "has_dot_variation": null,
        "has_plus_addressing": null,
        "has_special_characters": null,
        "has_numeric": null,
        "has_hyphen": null,
        "has_underscore": null,
        "is_quoted": null
      },
      "domain": {
        "category": "unknown",
        "free_provider": null,
        "punycode_value": null,
        "has_valid_tld": null,
        "has_website": null,
        "has_punycode": null,
        "has_typo_mismatch": null,
        "is_ipv4": null,
        "is_ipv6": null,
        "is_only_numeric": null,
        "is_single_label": null,
        "subdomain": {
          "count": null,
          "has_hyphen": null,
          "has_numeric": null,
          "has_uuid": null,
          "has_wildcard": null
        }
      }
    }
  },
  "ip": {
    "is_datacenter": false,
    "is_tor": false,
    "is_vpn": false
  },
  "velocity_by_email": {
    "items": [
      {
        "passed_email": "go1@012.net.il",
        "created_at": 1789839966
      }
    ],
    "count": 1
  },
  "velocity_by_ip": {
    "items": [
      {
        "ipv4_address": "127.0.0.1",
        "ipv6_address": null,
        "created_at": 1789839966
      }
    ],
    "count": 1
  }
}

Status Codes

Test With Custom Policy

For testing and development purposes, you may include an optional custom_policy parameter in your request body to define specific validation rules.

Example Request with Custom Policy

{
  "email_address": "user@example.com",
  "custom_policy": {
    "parent_rules": [
      {
        "action": "block",
        "field": "domain_disposable",
        "operator": "==",
        "target": {
          "bool": true
        }
      },
      {
        "action": "block",
        "field": "email_deliverable",
        "operator": "==",
        "target": {
          "bool": false
        }
      },
      {
        "action": "ignore",
        "field": "domain_free",
        "operator": "==",
        "target": {
          "bool": true
        }
      }
    ],
    "stop_on_block": true,
    "version": "1.0"
  }
}