API Version 1

See the following links for information on:

• API Overview & General Concepts
  • Authentication
  • Errors
  • API v1 compared to API v2
  • Important Data Explanations
• API v1 (currently viewing)
• API v2

NEW! Check Out ArkVision

What is ArkVision?

ArkVision is a scoring and alerts system that shines a different perspective on ArkOwl data. This new view of ArkOwl data will make training and API implementations easier as well as help communicate new data features going forward.

Check out the documentation for ArkVision below!

Combined Query

The best endpoint to use to perform an ArkOwl query is the combined endpoint. This allows you to send multiple data points in one request. Another advantage is we are able to add some additional correlation data between the data points (if available).

Combined Endpoint

https://api.arkowl.com/v1/combined

Combined Request Parameters

All query endpoints support GET and POST requests. These are the available parameters:

* For combined queries, at least one of the following is required: email or phone. A query will be rejected if missing both of these inputs.

Sending Parameters

Whether using GET or POST, all parameters need to be sent in the query parameters. A couple notes:

1. The email address may need to be url-encoded if it contains unsafe characters such as %,/,#, or ?, however these are uncommon in email addresses. See the strict option for more information
2. If passing a phone number with the + symbol in the query parameters, you will need to url-encoded the parameters. The reason is because query parameters interpret + as a blank space character. By encoding the parameters first, the + is converted to the URL encoded value of %2B.

Example parameters and request:

{
  "email": "john.doe@example.com",
  "phone": "+1-612-555-3333",
  "ip": "77.7.777.175",
  "address_name": "Prime BBQ",
  "address_line_1": "403 Knightdale Station Run",
  "address_line_2": "Suite 4",
  "address_locality": "Knightdale",
  "address_region": "NC",
  "address_postal_code": "27545",
  "address_country_code": "US"
}

$ curl https://api.arkowl.com/v1/combined?email=john.doe%40example.com&phone=%2B1-612-555-3333&ip=77.7.777.175&address_name=Prime%BBQ&address_line_1=403%Knightdale%20Station%20Run&address_line_2=Suitet%204&address_locality=Knightdale&address_region=NC&address_postal_code=27545&address_country_code=US \
    -u YOUR_API_KEY:

Combined Example Response

Here is an example API response for version 1:

{
  "email_phone_connection": true,
  "deeplink": "https://arkowl.com/query?email=john.doe%40example.com&phone=%2B1-612-555-3333&ip=77.7.777.175&address_name=Prime%20BBQ&address_line_1=403%20Knightdale%20Station%20Run&address_line_2=&address_country_code=US&address_postal_code=27545&address_region=NC&address_locality=Knightdale",
  "email_data": {
    "handle": "test.example",
    "query": "test.example@gmail.com",
    "id": "test.example@gmail.com",
    "exists": "yes",
    "registrar": "google",
    "no_data": false,
    "known_aliases": [
      "testexample@gmail.com"
    ],
    "created": null,
    "created_after": null,
    "created_before": 1481436000,
    "days_old": null,
    "first_seen_anywhere": 1331154455,
    "first_seen": 1331154455,
    "last_seen": 1697839287,
    "times_seen": 70,
    "email_handle_to_email_name_match": 15.47,
    "email_handle_to_email_name__char_match": false,
    "data_breaches": [
      {
        "name": "Data Enrichment Exposure From PDL Customer",
        "domain": "",
        "breach_date": 1571202000,
        "description": "In October 2019, <a href=\"https://www.troyhunt.com/data-enrichment-people-data-labs-and-another-622m-email-addresses\" target=\"_blank\" rel=\"noopener\">security researchers Vinny Troia and Bob Diachenko identified an unprotected Elasticsearch server holding 1.2 billion records of personal data</a>. The exposed data included an index indicating it was sourced from data enrichment company People Data Labs (PDL) and contained 622 million unique email addresses. The server was not owned by PDL and it's believed a customer failed to properly secure the database. Exposed information included email addresses, phone numbers, social media profiles and job history data.",
        "data_classes": [
          "email addresses",
          "employers",
          "geographic locations",
          "job titles",
          "names",
          "phone numbers",
          "social media profiles"
        ]
      },
      {
        "name": "Gravatar",
        "domain": "gravatar.com",
        "breach_date": 1601701200,
        "description": "In October 2020, <a href=\"https://www.bleepingcomputer.com/news/security/online-avatar-service-gravatar-allows-mass-collection-of-user-info/\" target=\"_blank\" rel=\"noopener\">a security researcher published a technique for scraping large volumes of data from Gravatar, the service for providing globally unique avatars </a>. 167 million names, usernames and MD5 hashes of email addresses used to reference users' avatars were subsequently scraped and distributed within the hacking community. 114 million of the MD5 hashes were cracked and distributed alongside the source hash, thus disclosing the original email address and accompanying data. Following the impacted email addresses being searchable in HIBP, <a href=\"https://en.gravatar.com/support/data-privacy\" target=\"_blank\" rel=\"noopener\">Gravatar release an FAQ detailing the incident</a>.",
        "data_classes": [
          "email addresses",
          "names",
          "usernames"
        ]
      }
    ],
    "data_breaches_error": false,
    "accounts": {
      "google": {
        "status": "registered",
        "metadata": {
          "parsed": "testexample@gmail.com",
          "handle": "test.example@gmail.com",
          "account_id": "113779123123123123123123",
          "profile_img": "https://lh3.googleusercontent.com/a-/ALV-UjVo7DrW0ifpvf5stsX998AHFSaIHoyravSKaGjc",
          "full_name": "Johnny Doe",
          "first_known_activity": 1481436000
        }
      },
      "gravatar": {
        "status": "registered",
        "metadata": {
          "profile_img": "https://www.gravatar.com/avatar/975810eefdf6a23b36f5b1c7a327a59c?r=r&s=280&d=404"
        }
      },
      "microsoft": {
        "status": "unregistered",
        "metadata": {}
      },
      "skype": {
        "status": "registered",
        "metadata": {
          "full_name": "John Doe",
          "profile_img": "https://avatar.skype.com/v1/avatars/johndoe/public",
          "city": null,
          "state": null,
          "country": "United States",
          "country_code": "US",
          "language": null,
          "onedrive_exists": true,
          "onedrive_created": 1399146370
        }
      },
      "spotify": {
        "status": "registered",
        "metadata": {}
      },
      "twitter": {
        "status": "unregistered",
        "metadata": {}
      },
      "yahoo": {
        "status": "registered",
        "metadata": {
          "temporary_email": false
        }
      }
    },
    "domain_registrations": {
      "error": false,
      "intelligence": {
        "domains_registered": [
          "some-example-domain.com"
        ],
        "unique_domains_registered": 1,
        "earliest_domain_registration": 1435276800,
        "days_since_earliest_domain_registration": 3692,
        "unique_phones_connected": 1,
        "known_names": [
          "John Doe"
        ]
      }
    },
    "domain": {
      "id": "gmail.com",
      "suffix": "com",
      "valid": true,
      "exists": true,
      "registrar": "MarkMonitor Inc.",
      "registered": 808203600,
      "updated": 1689051600,
      "expires": 1723352400,
      "first_seen": 1335853690,
      "last_seen": 1702302316,
      "known_disposable_email_provider": false,
      "isp_provided_email": false,
      "free_email_provide": false,
      "parent_company": null,
      "domain_description": null,
      "favicon": "https://t0.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=https://arkowl.com&size=64",
      "registrant": {
        "name": null,
        "organization": "Google LLC",
        "street1": null,
        "street2": null,
        "street3": null,
        "city": null,
        "state": "CA",
        "postal_code": null,
        "country": "UNITED STATES",
        "email": "abusecomplaints@markmonitor.com",
        "phone": null,
        "fax": null
      },
      "registration_history": [
        {
          "registered_date": "2013-10-08T00:00:00.000Z",
          "registrar_name": "MarkMonitor, Inc.",
          "registrar_website": "http://www.markmonitor.com",
          "registrant_name": null,
          "registrant_company": "Google LLC",
          "registrant_email": "select request email form at https://domains.markmonitor.com/whois/gmail.com",
          "registrant_address": null,
          "registrant_city": null,
          "registrant_state": "CA",
          "registrant_country": "US",
          "registrant_zip": null
        },
        {
          "registered_date": "2010-08-12T00:00:00.000Z",
          "registrar_name": "MarkMonitor, Inc.",
          "registrar_website": "http://www.markmonitor.com",
          "registrant_name": null,
          "registrant_company": "Google LLC",
          "registrant_email": null,
          "registrant_address": null,
          "registrant_city": null,
          "registrant_state": "CA",
          "registrant_country": "US",
          "registrant_zip": null
        }
      ],
      "contacts": [
        {
          "type": "Technical",
          "name": null,
          "organization": "Google LLC",
          "street1": null,
          "street2": null,
          "street3": null,
          "city": null,
          "state": "CA",
          "postal_code": null,
          "country": "UNITED STATES",
          "email": null,
          "phone": null,
          "fax": null
        },
        {
          "type": "Administrative",
          "name": null,
          "organization": "Google LLC",
          "street1": null,
          "street2": null,
          "street3": null,
          "city": null,
          "state": "CA",
          "postal_code": null,
          "country": "UNITED STATES",
          "email": null,
          "phone": null,
          "fax": null
        }
      ],
      "mail_servers": [
        "05 gmail-smtp-in.l.google.com",
        "10 alt1.gmail-smtp-in.l.google.com",
        "20 alt2.gmail-smtp-in.l.google.com",
        "30 alt3.gmail-smtp-in.l.google.com",
        "40 alt4.gmail-smtp-in.l.google.com"
      ],
      "name_servers": [
        "ns1.google.com",
        "ns2.google.com",
        "ns3.google.com",
        "ns4.google.com"
      ],
      "bad_activity": {
        "total_reports": 123,
        "reports_last_24h": 3,
        "reports_last_7d": 12,
        "reports_last_30d": 40,
        "first_report": 1336176000,
        "last_report": 1715806831,
        "seen_domains": [
          "gmail.com",
          "mail.gmail.com"
        ],
        "unique_handles": 57,
        "excluded": false,
        "error": false
      }
    },
    "bad_activity": {
      "disposable_email": false,
      "blacklisted": true,
      "reports": 11,
      "reports_last_24h": 0,
      "reports_last_7d": 2,
      "reports_last_30d": 5,
      "first_report": 1715806831,
      "last_report": 1715806831,
      "error": false
    }
  },
  "phone_data": {
    "query": "16125553333",
    "id": "+16125553333",
    "formatted": "+1 612-555-3333",
    "valid": true,
    "exists": "unverified",
    "first_seen_anywhere": 1570646136,
    "first_seen": 1570646136,
    "last_seen": 1697839288,
    "times_seen": 33,
    "name": "JOHN DOE",
    "region": "US",
    "carrier": "Cingular Wireless/2",
    "linetype": "mobile",
    "geo_location": "Minnesota",
    "timezone": "America/Chicago",
    "coordinates": "44.9708,-93.32084",
    "data_breaches": [],
    "data_breaches_error": false,
    "accounts": {
      "skype": {
        "status": "registered",
        "metadata": {
          "full_name": "Johnny Carlson",
          "profile_img": "https://avatar.skype.com/v1/avatars/johnnycarlson/public",
          "city": null,
          "state": null,
          "country": "United States",
          "country_code": "US",
          "language": null
        }
      }
    },
    "domain_registrations": {
      "error": false,
      "intelligence": {
        "domains_registered": [
          "some-example-domain.com",
          "another-example-domain.com"
        ],
        "unique_domains_registered": 2,
        "earliest_domain_registration": 1435276800,
        "days_since_earliest_domain_registration": 3692,
        "unique_emails_connected": 2,
        "emails_connected": [
          "test.example@gmail.com",
          "another.test@gmail.com"
        ],
        "known_names": [
          "John Doe",
          "Jonathan Doe"
        ]
      }
    }
  },
  "ip_data": {
    "query": "77.7.777.175",
    "id": "77.7.777.175",
    "valid": true,
    "ipv6": false,
    "private": false,
    "reserved": false,
    "organization": "Comcast Cable",
    "network": "77.7.777.175/32",
    "country": "United States",
    "country_code": "US",
    "city": "Brooklyn Center",
    "state": "MN",
    "postal_code": "55429",
    "timezone": "America/Chicago",
    "location": "Brooklyn Center, Minnesota, United States",
    "coordinates": "45.052,-93.336",
    "accuracy_radius": 5,
    "first_seen": 1665035754,
    "last_seen": 1697839288,
    "times_seen": 3
  },
  "address_data": {
    "query": {
      "formatted": "Prime Champ, 403 Knightdale Station Run, Knightdale, NC, 27545, US",
      "name": "Prime CHAMP",
      "line_1": "403 KNIGHTDALE STATION RUN",
      "line_2": "Suite 4",
      "locality": "KNIGHTDALE",
      "region": "NC",
      "postal_code": "27545",
      "country_code": "US"
    },
    "name": "Prime CHAMP",
    "line_1": "403 Knightdale Station Run",
    "line_2": null,
    "locality": "Knightdale",
    "region": "NC",
    "postal_code": "27545",
    "country": "United States of America (the)",
    "country_code": "USA",
    "coordinates": "35.7968,-78.4713",
    "place_id": "5150c293552a9e53c0124abee54140f00102f901ca58951c00000000c00203",
    "place_name": null,
    "place_category": null,
    "county": "Wake County",
    "result_type": "building",
    "match_type": "full_match",
    "confidence": 1,
    "confidence_city_level": 1,
    "confidence_street_level": 1,
    "popularity": 2.4415236216901155,
    "importance": 0.00000999999999995449,
    "formatted": "403 Knightdale Station Run, Knightdale, NC 27545, United States of America",
    "timezone": "America/New_York",
    "timezone_alt": null
  },
  "meta_data": {
    "email_phone_connection": true,
    "email_phone_queried_together_first_seen": 1648265438,
    "email_phone_queried_together_last_seen": 1681481490,
    "email_phone_queried_together_times_seen": 8,
    "email_phone_name_match": 76.92,
    "email_handle_to_email_name_match": 15.47,
    "email_handle_to_phone_name_match": 12.03,
    "email_handle_to_email_name__char_match": false,
    "email_handle_to_phone_name__char_match": false,
    "address_email_name_match": 100,
    "address_phone_name_match": 76.92,
    "email_phone_social_match": true,
    "email_phone_number_of_social_matches": 1,
    "email_phone_full_mfa_match": null,
    "email_phone_partial_mfa_match": true,
    "email_phone_number_of_mfa_matches": 1,
    "email_ip_country_match": true,
    "email_phone_country_match": true,
    "address_email_country_match": true,
    "phone_ip_country_match": true,
    "address_phone_country_match": true,
    "address_ip_country_match": true,
    "email_phone_timezone_match": true,
    "email_ip_timezone_match": true,
    "address_email_timezone_match": null,
    "phone_ip_timezone_match": true,
    "address_phone_timezone_match": null,
    "address_ip_timezone_match": null,
    "distances": {
      "address_min_dist_to_email": 4.03,
      "address_dist_to_ip": 12.01,
      "address_dist_to_phone": 8.94,
      "ip_min_dist_to_email": 9.63,
      "ip_dist_to_phone": 5.66,
      "phone_min_dist_to_email": 8.6,
      "avg_distances": 8.145
    }
  },
  "arkvision": {
    "score": 35,
    "min_possible": -64,
    "max_possible": 160,
    "rule_set_id": "8",
    "rule_set_name": "ArkOwl's Base Ruleset",
    "alert": "yellow",
    "highest_triggered_rule_alert_message": "Potential bad actor using a disposable email",
    "threshold_crossed": null,
    "green_score_threshold": 65,
    "yellow_score_threshold": 46,
    "red_score_threshold": 36,
    "green_score_message": "Low Risk",
    "yellow_score_message": "Above Average Risk",
    "red_score_message": "Super Risky!",
    "scoring_rules": [
      {
        "rule_passed": false,
        "output": "correlations.email__phone.name_match_percent",
        "comparison": "gt",
        "target_value": 90,
        "actual_value": null,
        "score_effect": 2,
        "alert_color": "",
        "alert_message": "",
        "group_id": null,
        "description": "Email and Phone Connection match via character matching of the name - 90% namematch or higher",
        "output_title": "correlations.email__phone.name_match_percent",
        "logic_description": "correlations.email__phone.name_match_percent > 90"
      },
      {
        "rule_passed": true,
        "output": "phone.accounts.teams.registered",
        "comparison": "equal",
        "target_value": true,
        "actual_value": true,
        "score_effect": 1,
        "alert_color": "",
        "alert_message": "",
        "group_id": null,
        "description": "Phone Number is associated with a Microsoft Teams account",
        "output_title": "Phone Accounts Teams Registered",
        "logic_description": "Phone Accounts Teams Registered = True"
      },
      {
        "rule_passed": false,
        "output": "email.domain.exists",
        "comparison": "equal",
        "target_value": false,
        "actual_value": true,
        "score_effect": -10,
        "alert_color": "yellow",
        "alert_message": "Domain does not exist, high likelihood for bad actor",
        "group_id": null,
        "description": "Email domain does not exist.",
        "output_title": "Email Domain Exists",
        "logic_description": "Email Domain Exists = False"
      },
      {
        "rule_passed": true,
        "output": "email.data_breaches.earliest",
        "comparison": "gt",
        "target_value": 720,
        "actual_value": 1000,
        "score_effect": -4,
        "alert_color": "",
        "alert_message": "",
        "group_id": "12345",
        "description": "Email was first seen in a data breach more than 2 years ago",
        "output_title": "email.data_breaches.earliest",
        "logic_description": "email.data_breaches.earliest > 720 Days"
      },
      {
        "rule_passed": true,
        "output": "email.domain.disposable",
        "comparison": "equal",
        "target_value": true,
        "actual_value": true,
        "score_effect": -10,
        "alert_color": "yellow",
        "alert_message": "Potential bad actor using a disposable email",
        "group_id": "12345",
        "description": "Email domain issues disposable emails",
        "output_title": "Disposable Email",
        "logic_description": "email.domain.disposable = True"
      },
      ...
    ]
  }
}

See Response Fields for details on this object.

Email Query

Note: it is recommended that the /combined endpoint be used over this endpoint.

Email Endpoint

https://api.arkowl.com/v1/email/{emailAddressToQuery}

Email Request Parameters

All query endpoints support GET and POST requests. These are the available parameters:

Email Example Response

Here is a partial example of an API response for version 1 email only endpoint. The fields will be the exact same as the nested email_data object in the /combined endpoint response:

{
  "id": "test@example.com",
  "query": "TEST@example.com",
  ...
}

See Email Response Fields for details on this object.

Phone Number Query

Note: it is recommended that the /combined endpoint be used over this endpoint.

Phone Number Endpoint

https://api.arkowl.com/v1/phone/{phoneNumberToQuery}

Phone Number Request Parameters

All query endpoints support GET and POST requests. These are the available parameters:

Example Phone Number Response

Here is a partial example of an API response for version 1 phone only endpoint. The fields will be the exact same as the nested phone_data object in the /combined endpoint response:

{
  "query": "+1-612-220-3333",
  "id": "+16125553333",
  "formatted": "+1 612-220-3333"
  ...
}

See Phone Number Response Fields for details on this object.

Response Fields

Below are all response fields, their types, and a short description of each field.

Combined Response Fields

• For important information about social checks, please reference this documentation.
• Additionally, check out this reference for null data types

Email Response Fields

• For important information about social checks, please reference this documentation.
• Additionally, check out this reference for null data types
• If using the /combined endpoint, this response object will be nested at the top level email_data. See the Combined Response Fields for more details.
• If using the /email endpoint, this response will be the body of the response.

Phone Number Response Fields

• For important information about social checks, please reference this documentation.
• Additionally, check out this reference for null data types
• If using the /combined endpoint, this response object will be nested at the top level phone_data. See the Combined Response Fields for more details.
• If using the /phone endpoint, this response will be the body of the response.

IP Address Response Fields

• Check out this reference for null data types
• IP data is only available when using the /combined endpoint. This response object will be nested at the top level ip_data. See the Combined Response Fields for more details.

Address Response Fields

• Check out this reference for null data types
• Address data is only available when using the /combined endpoint. This response object will be nested at the top level address_data. See the Combined Response Fields for more details.

Metadata Response Fields

• Check out this reference for null data types
• Address data is only available when using the /combined endpoint. This response object will be nested at the top level address_data. See the Combined Response Fields for more details.
• null will be returned if there is not enough information to determine a match.

ArkVision

ArkVision is a scoring and alerts system that shines a different perspective on ArkOwl data. This new view of ArkOwl data will make training and API implementations easier as well as help communicate new data features going forward.

• ArkVision is only available when using the /combined endpoint. This response object will be nested at the top level arkvision. See the Combined Response Fields for more details.

The top level "arkvision": {...} object will only appear in the query response if the feature is enabled for your account.

If the feature is enabled, but the manager of the account has turned if off or does not have a selected ArkVision Rule Set, then it will return as null. Example:

{
  "email_data": {...},
  "phone_data": {...},
  "ip_data": {...},
  "address_data": {...},
  "meta_data": {...},
  "arkvision": null
}

When the ArkVision is present, it will have the following object schema:

Feedback

Let us know if you have any questions or comments about the documentation!