API Version 2

API Version 2 is known as the “flat” API. The reason being that the returned JSON response only has top level object keys and no nested objects or arrays.

See the following links for information on:

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

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/v2/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/v2/combined?email=john.doe%40example.com&phone=%2B1-612-555-3333&ip=77.7.777.175&address_name=John%20Doe&address_line_1=700%20Fake%20St.&address_line_2=Apt%20333&address_locality=Kings%20City&address_region=California&address_postal_code=12345&address_country_code=US \
    -u YOUR_API_KEY:

Combined Example Response

Here is an example API response for version 2:

{
  "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.handle" : "test.example",
  "email.query": "test.example@gmail.com",
  "email.error": false,
  "email.normalized": "test.example@gmail.com",
  "email.exists": "yes",
  "email.no_data": false,
  "email.registrar": "google",
  "email.known_aliases": "testexample@gmail.com, testexample+fb@gmail.com",
  "email.created": null,
  "email.created_after": null,
  "email.created_before": "2016-12-18T00:00:00-06:00",
  "email.first_seen_anywhere": "2012-03-22T00:00:00-05:00",
  "email.first_seen": "2023-01-03T10:13:32-06:00",
  "email.last_seen": "2023-12-13T05:29:08-06:00",
  "email.times_seen": 694,
  "email.email_handle_to_email_name_match": 15.47,
  "email.email_handle_to_email_name__char_match": false,
  "email.data_breaches.known": 13,
  "email.data_breaches.earliest": "2012-03-22T00:00:00-05:00",
  "email.data_breaches.latest": "2021-04-08T00:00:00-05:00",
  "email.data_breaches.error": false,
  "email.bad_activity.disposable_email": false,
  "email.bad_activity.blacklisted": false,
  "email.bad_activity.reports": 0,
  "email.bad_activity.reports_last_24h": null,
  "email.bad_activity.reports_last_7d": null,
  "email.bad_activity.reports_last_30d": null,
  "email.bad_activity.first_report": null,
  "email.bad_activity.last_report": null,
  "email.bad_activity.error": false,
  "email.domain.isp_provided_email": false,
  "email.domain.free_email_provide": false,
  "email.domain.parent_company": null,
  "email.domain_description": null,
  "email.domain.favicon": "https://t0.gstatic.com/faviconV2?client=SOCIAL&type=FAVICON&fallback_opts=TYPE,SIZE,URL&url=https://arkowl.com&size=64",
  "email.domain.bad_activity.total_reports": 123,
  "email.domain.bad_activity.reports_last_24h": 3,
  "email.domain.bad_activity.reports_last_7d": 12,
  "email.domain.bad_activity.reports_last_30d": 40,
  "email.domain.bad_activity.first_report": 1336176000,
  "email.domain.bad_activity.last_report": 1715806831,
  "email.domain.bad_activity.seen_domains": 1,
  "email.domain.bad_activity.unique_handles": 57,
  "email.domain.bad_activity.excluded": false,
  "email.domain.bad_activity.error": false,
  "email.domain_registrations.error": false,
  "email.domain_registrations.unique_domains_registered": 1,
  "email.domain_registrations.earliest_domain_registration": 1435276800,
  "email.domain_registrations.days_since_earliest_domain_registration": 3692,
  "email.domain_registrations.unique_phones_connected": 1,
  "email.registered_accounts": 5,
  "email.accounts.google.registered": true,
  "email.accounts.google.parsed_email": "test.example@gmail.com",
  "email.accounts.google.actual_email": "test.example@gmail.com",
  "email.accounts.google.account_id": "113779482880962429075",
  "email.accounts.google.profile_img": "https://lh3.googleusercontent.com/a-/ALV-UjVo7DrW0ifpvf5stsX99whny8AHFSaIHoXeKyravSKaGjc",
  "email.accounts.google.full_name": "Johnny Doe",
  "email.accounts.google.first_known_activity": "2016-12-18T00:00:00-06:00",
  "email.accounts.gravatar.registered": true,
  "email.accounts.gravatar.profile_img": "https://www.gravatar.com/avatar/975810eefdf6a23b36f5b1c7a327a59c?r=r&s=280&d=404",
  "email.accounts.microsoft.registered": false,
  "email.accounts.skype.registered": true,
  "email.accounts.skype.full_name": "John Doe",
  "email.accounts.skype.profile_img": "https://avatar.skype.com/v1/avatars/johndoe/public",
  "email.accounts.skype.city": "New York",
  "email.accounts.skype.state": "NY",
  "email.accounts.skype.country": "United States",
  "email.accounts.skype.country_code": "US",
  "email.accounts.skype.language": null,
  "email.accounts.skype.onedrive_exists": true,
  "email.accounts.skype.onedrive_created": "2021-12-13T07:20:08-06:00",
  "email.accounts.spotify.registered": true,
  "email.accounts.twitter.registered": true,
  "email.accounts.yahoo.registered": true,
  "email.accounts.yahoo.temp_email": false,
  "email.accounts.yahoo.temporary_email": false,
  "email.domain.hostname": "gmail.com",
  "email.domain.suffix": "com",
  "email.domain.valid": true,
  "email.domain.exists": true,
  "email.domain.registrar": "MarkMonitor Inc.",
  "email.domain.registered": "1995-08-13",
  "email.domain.updated": "2023-07-11",
  "email.domain.expires": "2024-08-12",
  "email.domain.first_seen": "2023-11-01T10:26:52-05:00",
  "email.domain.last_seen": "2023-12-13T05:29:05-06:00",
  "email.domain.registrant.name": null,
  "email.domain.registrant.organization": "Google LLC",
  "email.domain.registrant.address": "100 Fake Google Street",
  "email.domain.registrant.city": "San Google",
  "email.domain.registrant.state": "CA",
  "email.domain.registrant.postal_code": "12345",
  "email.domain.registrant.country": "UNITED STATES",
  "email.domain.registrant.email": "abusecomplaints@markmonitor.com",
  "email.domain.registrant.phone": "+1 800-555-0000",
  "phone.query": "16125553333",
  "phone.error": false,
  "phone.normalized": "+16125553333",
  "phone.formatted": "+1 612-555-3333",
  "phone.valid": true,
  "phone.exists": "unverified",
  "phone.first_seen_anywhere": "2022-12-08T12:48:32-06:00",
  "phone.first_seen": "2022-12-08T12:48:32-06:00",
  "phone.last_seen": "2023-12-14T12:36:08-06:00",
  "phone.times_seen": 173,
  "phone.name": "JOHN DOE",
  "phone.region": "US",
  "phone.carrier": "AERIAL COMMUNICATIONS",
  "phone.linetype": "mobile",
  "phone.geo_location": "Minnesota",
  "phone.timezone": "America/Chicago",
  "phone.coordinates": "44.9708,-93.32084",
  "phone.data_breaches.known": 0,
  "phone.data_breaches.earliest": null,
  "phone.data_breaches.latest": null,
  "phone.data_breaches.error": false,
  "phone.registered_accounts": 1,
  "phone.accounts.twitter.registered": true,
  "phone.accounts.skype.registered": true,
  "phone.accounts.skype.full_name": "Johnny Carlson",
  "phone.accounts.skype.profile_img": "https://avatar.skype.com/v1/avatars/johnnycarlson/public",
  "phone.accounts.skype.city": "Wendel",
  "phone.accounts.skype.state": "CA",
  "phone.accounts.skype.country": "United States",
  "phone.accounts.skype.country_code": "US",
  "phone.accounts.skype.language": "EN",
  "phone.domain_registrations.error": false,
  "phone.domain_registrations.unique_domains_registered": 2,
  "phone.domain_registrations.earliest_domain_registration": 1435276800,
  "phone.domain_registrations.days_since_earliest_domain_registration": 3692,
  "phone.domain_registrations.unique_emails_connected": 2,
  "ip.query": "77.7.777.175",
  "ip.normalized": "77.7.777.175",
  "ip.error": false,
  "ip.valid": true,
  "ip.ipv6": false,
  "ip.private": false,
  "ip.reserved": false,
  "ip.first_seen": "2022-12-08T12:48:32-06:00",
  "ip.last_seen": "2023-12-14T12:36:08-06:00",
  "ip.times_seen": 157,
  "ip.organization": "Comcast Cable",
  "ip.network": "77.7.777.175/32",
  "ip.location": "Brooklyn Center, Minnesota, United States",
  "ip.coordinates": "45.052,-93.336",
  "ip.accuracy_radius": 5,
  "address.query": "Prime Champ, 403 Knightdale Station Run, Knightdale, NC, 27545, US",
  "address.formatted":  "403 Knightdale Station Run, Knightdale, NC 27545, United States of America",
  "address.name":  "Prime CHAMP",
  "address.line_1": "403 Knightdale Station Run",
  "address.line_2": null,
  "address.locality": "Knightdale",
  "address.region": "NC",
  "address.postal_code": "27545",
  "address.country":  "United States of America (the)",
  "address.country_code": "USA",
  "address.county": "Wake County",
  "address.coordinates":  "35.7968,-78.4713",
  "address.place_id": "5150c293552a9e53c0124abee54140f00102f901ca58951c00000000c00203",
  "address.place_name": null,
  "address.place_category": null,
  "address.result_type": "building",
  "address.match_type": "full_match",
  "address.confidence": 1,
  "address.confidence_city_level": 1,
  "address.confidence_street_level": 1,
  "address.popularity": 2.4415236216901155,
  "address.importance": 0.00000999999999995449,
  "address.timezone":  "America/New_York",
  "address.timezone_alt": null,
  "meta.email_phone_connection": true,
  "meta.email_phone_queried_together_first_seen": "2022-12-08T12:48:32-06:00",
  "meta.email_phone_queried_together_last_seen": "2023-12-13T05:29:09-06:00",
  "meta.email_phone_queried_together_times_seen": 114,
  "meta.address_email_name_match": null,
  "meta.address_phone_name_match": null,
  "meta.email_phone_name_match": 76.92,
  "meta.email_handle_to_email_name_match": 15.47,
  "meta.email_handle_to_phone_name_match": 12.03,
  "meta.email_handle_to_email_name__char_match": false,
  "meta.email_handle_to_phone_name__char_match": false,
  "meta.email_phone_social_match": true,
  "meta.email_phone_number_of_social_matches": 1,
  "meta.email_phone_full_mfa_match": null,
  "meta.email_phone_partial_mfa_match": true,
  "meta.email_phone_number_of_mfa_matches": 1,
  "meta.email_phone_country_match": true,
  "meta.email_ip_country_match": true,
  "meta.address_email_country_match": true,
  "meta.phone_ip_country_match": true,
  "meta.address_phone_country_match": true,
  "meta.address_ip_country_match": true,
  "meta.email_phone_timezone_match": true,
  "meta.email_ip_timezone_match": true,
  "meta.address_email_timezone_match": null,
  "meta.phone_ip_timezone_match": true,
  "meta.address_phone_timezone_match": null,
  "meta.address_ip_timezone_match": null,
  "meta.distances.address_min_dist_to_email": 4.03,
  "meta.distances.address_dist_to_ip": 12.01,
  "meta.distances.address_dist_to_phone": 8.94,
  "meta.distances.ip_min_dist_to_email": 9.63,
  "meta.distances.ip_dist_to_phone": 5.66,
  "meta.distances.phone_min_dist_to_email": 8.6,
  "meta.distances.avg_distances": 8.145,
  "arkvision.score": 50,
  "arkvision.min_possible": 47,
  "arkvision.max_possible": 57,
  "arkvision.rule_set_name": "ArkVision Custom Rules",
  "arkvision.alert": "yellow",
  "arkvision.threshold_crossed": null,
  "arkvision.highest_triggered_rule_alert_message": "Email domain registered within the last 21 days",
  "arkvision.alert_message": "Review This Closely"
}

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/v2/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 2 email only endpoint. The fields will be the exact same as the email.* keys returned in the /combined endpoint response:

{
  "email.query": "TEST@example.com",
  "email.normalized": "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/v2/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 2 phone number only endpoint. The fields will be the exact same as the phone.* keys returned in the /combined endpoint response:

{
  "phone.query": "+1-612-220-3333",
  "phone.normalized": "+16125553333",
  "phone.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.
• All date fields are returned in the ATOM string representation which cooresponds to the “Date and Time with Offset” ISO 8601 standard. Example: 2021-04-08T00:00:00-05:00.

Phone Number Response Fields

• For important information about social checks, please reference this documentation.
• Additionally, check out this reference for null data types.
• All date fields are returned in the ATOM string representation which cooresponds to the “Date and Time with Offset” ISO 8601 standard. Example: 2021-04-08T00:00:00-05:00.

IP Address Response Fields

• Check out this reference for null data types.
• IP data is only available when using the /combined endpoint.
• All date fields are returned in the ATOM string representation which cooresponds to the “Date and Time with Offset” ISO 8601 standard. Example: 2021-04-08T00:00:00-05:00.

Address Response Fields

• Check out this reference for null data types.
• Address data is only available when using the /combined endpoint.

Metadata Response Fields

• Check out this reference for null data types.
• Address data is only available when using the /combined endpoint.
• 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.
• ArkVision fields 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 all the fields will return as null.
• See API v1 ArkVision if more detailed ArkVision data is needed.

Feedback

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