# 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:

```bash
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:

| Header      | Value               |
| :---------- | :------------------ |
| `x-api-key` | `YOUR_ACCESS_TOKEN` |

## Request Body

| Parameter       | Type     | Required | Description                                 |
| :-------------- | :------- | :------- | :------------------------------------------ |
| `email_address` | `string` | Yes      | The email address to be validated/analyzed. |

### Example Request

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

## Response

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

### Response Structure

```json
{
  "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",
        "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"
        }
      }
    }
  },
  "velocity_by_email": {
    "items": [
      {
        "base_email": "string",
        "created_at": "integer"
      }
    ],
    "count": "integer"
  }
}
```

### Response Fields

<details>
  <summary>Root Level</summary>

| Field               | Type     | Description                                          |
| :------------------ | :------- | :--------------------------------------------------- |
| `action`            | `string` | The final verdict: `allow`, `block`, or `ignore`.    |
| `email`             | `object` | Contains email analysis results.                     |
| `velocity_by_email` | `object` | Contains velocity tracking data for fraud detection. |

</details>

<details>
  <summary>Email Object</summary>

| Field        | Type     | Description                                        |
| :----------- | :------- | :------------------------------------------------- |
| `normalized` | `object` | Contains normalized versions of the email address. |
| `details`    | `object` | Contains detailed analysis of the email address.   |

</details>

<details>
  <summary>Normalized Emails Object</summary>

| Field                     | Type     | Description                                             |
| :------------------------ | :------- | :------------------------------------------------------ |
| `base`                    | `string` | The normalized base email address.                      |
| `without_plus_addressing` | `string` | Email address with plus addressing removed.             |
| `without_dot_variations`  | `string` | Email address with dot variations removed (Gmail only). |
| `without_punycode`        | `string` | Email address with punycode converted to Unicode.       |
| `without_typo_mismatch`   | `string` | Email address with common typos corrected.              |

</details>

<details>
  <summary>Email Details Object</summary>

| Field            | Type     | Description                                                                |
| :--------------- | :------- | :------------------------------------------------------------------------- |
| `deliverability` | `string` | Email deliverability status: `deliverable`, `undeliverable`, or `unknown`. |
| `local`          | `object` | Analysis of the email local part (before `@`).                             |
| `domain`         | `object` | Analysis of the email domain part (after `@`).                             |

</details>

<details>
  <summary>Email Local Details Object</summary>

| Field                    | Type      | Description                                                    |
| :----------------------- | :-------- | :------------------------------------------------------------- |
| `fraud_pattern`          | `string`  | Detected fraud pattern identifier (e.g., `high_entropy:0.95`). |
| `mixed_script`           | `string`  | Detected mixed script characters.                              |
| `has_fraud_pattern`      | `boolean` | Indicates if a fraud pattern was detected.                     |
| `has_mixed_script`       | `boolean` | Indicates if mixed scripts were detected.                      |
| `has_dot_variation`      | `boolean` | Indicates if the local part contains dots.                     |
| `has_plus_addressing`    | `boolean` | Indicates if plus addressing is used.                          |
| `has_special_characters` | `boolean` | Indicates if special characters are present.                   |
| `has_numeric`            | `boolean` | Indicates if numeric characters are present.                   |
| `has_hyphen`             | `boolean` | Indicates if hyphens are present.                              |
| `has_underscore`         | `boolean` | Indicates if underscores are present.                          |
| `is_quoted`              | `boolean` | Indicates if the local part is quoted.                         |

</details>

<details>
  <summary>Email Domain Details Object</summary>

| Field               | Type      | Description                                                                                 |
| :------------------ | :-------- | :------------------------------------------------------------------------------------------ |
| `category`          | `string`  | Domain category: `business`, `free`, `education`, `government`, `disposable`, or `unknown`. |
| `punycode_value`    | `string`  | The punycode representation of the domain if applicable.                                    |
| `has_valid_tld`     | `boolean` | Indicates if the top-level domain is valid.                                                 |
| `has_website`       | `boolean` | Indicates if the domain has an active website.                                              |
| `has_punycode`      | `boolean` | Indicates if the domain contains punycode.                                                  |
| `has_typo_mismatch` | `boolean` | Indicates if a typo was detected in the domain.                                             |
| `is_ipv4`           | `boolean` | Indicates if the domain is an IPv4 address.                                                 |
| `is_ipv6`           | `boolean` | Indicates if the domain is an IPv6 address.                                                 |
| `is_only_numeric`   | `boolean` | Indicates if the domain contains only numeric characters.                                   |
| `is_single_label`   | `boolean` | Indicates if the domain has only one label (no subdomains).                                 |
| `subdomain`         | `object`  | Subdomain analysis details.                                                                 |

</details>

<details>
  <summary>Email Subdomain Details Object</summary>

| Field          | Type      | Description                                         |
| :------------- | :-------- | :-------------------------------------------------- |
| `count`        | `integer` | Number of subdomain levels.                         |
| `has_hyphen`   | `boolean` | Indicates if subdomain contains hyphens.            |
| `has_numeric`  | `boolean` | Indicates if subdomain contains numeric characters. |
| `has_uuid`     | `boolean` | Indicates if subdomain contains a UUID pattern.     |
| `has_wildcard` | `boolean` | Indicates if subdomain contains a wildcard pattern. |

</details>

<details>
  <summary>Velocity By Email Object</summary>

| Field   | Type      | Description                                              |
| :------ | :-------- | :------------------------------------------------------- |
| `items` | `array`   | List of historical email occurrences for the base email. |
| `count` | `integer` | Total count of occurrences.                              |

</details>

<details>
  <summary>Velocity Item Object</summary>

| Field        | Type      | Description                                          |
| :----------- | :-------- | :--------------------------------------------------- |
| `base_email` | `string`  | The base email address for this occurrence.          |
| `created_at` | `integer` | Unix timestamp of when this occurrence was recorded. |

</details>

### Example Response

```json
{
  "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",
        "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
        }
      }
    }
  },
  "velocity_by_email": {
    "items": [],
    "count": 0
  }
}
```

### Status Codes

| Status Code | Details                       |
| ----------- | ----------------------------- |
| `200`       | Results returned successfully |
| `400`       | Invalid request parameters    |
| `401`       | Invalid or missing API key    |
| `500`       | Internal server error         |

## 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.

> [!CAUTION]
> This parameter is intended for testing environments only and is not required for standard API usage.

| Parameter     | Type | Required | Description                                                                |
| ------------- | ---- | -------- | -------------------------------------------------------------------------- |
| custom_policy | json | No       | A JSON object used to override default validation behavior during testing. |

### Example Request with Custom Policy

```json
{
  "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
        }i
      }
    ],
    "stop_on_block": true,
    "version": "1.0"
  }
}
```