API Reference

The ArkOwl API is organized around REST. Our API is designed to have predictable, resource-oriented URLs and to use HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which can be understood by off-the-shelf HTTP clients. JSON should be returned in all responses from the API, including errors.

This is the API overview page. If you are looking for specific API version documentation, check out:

• API v1 Documentation
• API v2 Documentation.

Authentication

You authenticate to the ArkOwl API by providing your secret API key in the request. Please reach out to us to have a key created or removed. Managers can view active API keys from their account dashboard. Your API keys carry many privileges, so be sure to keep them secret!

Authentication to the API occurs via HTTP Basic Auth. Provide your API key as the basic auth username. You do not need to provide a password. Your HTTP client should encode your key into a base64 string and include it in the HTTP Authorization: Basic header. For more information, see https://en.wikipedia.org/wiki/Basic_access_authentication

$ curl https://api.arkowl.com/v1/email/most.interesting@yahoo.com \
   -u YOUR_API_KEY:

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. You must authenticate for all requests.

Errors

ArkOwl uses conventional HTTP response codes to indicate success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that resulted from the provided information (e.g. a required parameter was missing), and codes in the 5xx range indicate an error with ArkOwl’s servers.

Example request with an invalid email:

$ curl https://api.arkowl.com/v1/email/example@foo \
   -u YOUR_API_KEY:

Example error response:

{
  "error": {
    "code": 400,
    "type": "invalid_request_error",
    "message": "Invalid email address provided: 'example@foo'"
  }
}

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but could not be fulfilled due to an empty account balance, we return a 402 error code.

HTTP Status Code Summary

HTTP Code Status Meaning

Error Attributes

The JSON responses will contain the following attributes within an error object:

API Versions

There are two API versions currently available: API v1 & API v2. The returned data is derived from the same sources; however, the formatting is different between the two. This causes some slight variants between them. Please review both to make a more accurate decision of which would better serve your API needs.

API v1 Overview

This version utilizes JSON’s ability to have nested objects and arrays. This is the most common use case for most modern APIs. See the provided partial example for a slimmed down response object with nested properties and arrays. See API v1 documentation for further details.

Partial Example Response (some fields omitted):

{
    "id": "most.interesting@yahoo.com",
    ...
    "known_aliases": [
        "angryarkowl@yahoo.com"
    ],
    "data_breaches": [
        {
            "name": "Dropbox",
            "domain": "dropbox.com",
            "breach_date": 1341118800,
            "description": "In mid-2012, Dropbox suffered a data breach which exposed the stored credentials of tens of millions of their customers...",
            "data_classes": [
                "email addresses",
                "passwords"
            ]
        }
    ],
    "accounts": {
        "google": {
            "status": "registered",
            "metadata": {
                "parsed": "most.interesting@yahoo.com",
                "account_id": "103289335359643770955",
                "profile_url": "//plus.google.com/u/1/103289335359643770955",
                "profile_img": null,
                "full_name": "Rob Prevent",
                "tagline": null
            }
        }
        ...
    },
    "domain": {
        "id": "yahoo.com",
        ...
        "contacts": [...],
        "mail_servers": [...],
        "name_servers": [...]
    }
}

Use Cases

Here are a few uses cases and possible advantages to using v1:

• Standard JSON response objects with nested objects and arrays.
• More verbose data for certain fields such as data_breaches and domain registrant information.
• Dates are in UNIX timestamps (in seconds) instead of string representations.

API v2 Overview

This version still returns a JSON object, however, it only uses top level fields on the returned object (ie. no nested objects or arrays). See the provided partial example for a slimmed down response object demonstrating these top level fields. Because of this, we often refer to API v2 as our “flat” API. See API v2 documentation for further details.

Partial Example Response (some fields omitted):

{
  "email.query": "arkowldemo@gmail.com",
  ...
  "email.data_breaches.known": 13,
  "email.data_breaches.earliest": "2012-03-22T00:00:00-05:00",
  "email.data_breaches.latest": "2018-09-12T00:00:00-05:00",
  ...
  "email.accounts.google.registered": true,
  "email.accounts.google.parsed_email": "arkowldemo@gmail.com",
  "email.accounts.google.actual_email": "arkowldemo@gmail.com",
  "email.accounts.google.account_id": "117804332923293394987",
  "email.accounts.google.profile_img": "https://lh3.googleusercontent.com/a-/AOh14GhCZkeBc6LuL0tBlEKcaFqphkuYhUae033GBY_f",
  "email.accounts.google.full_name": null,
  ...
  "email.domain.hostname": "gmail.com",
  ...
}

Use Cases Here are a few uses cases and possible advantages to using v2:

• Top level, quick access to data points
• Reduces the need for “falsy” checks on the response
• Ease of formatting to an export file like a .csv
• Dates are in string format compared to UNIX timestamps

Other Considerations There are some potential disadvantages to using v2:

• Less details for certain data points such as "email.data_breaches" (only a count and dates are returned)
• Some array values are not present such as email.domain.name_servers

Important Data Explanations

Social Account Check Information

Account Availability and Future Expansion

We may add or remove account checks and add or remove associated metadata based on data availability, performance, third-party obligations, or account-holder preferences. As such, the keys within the accounts object for email and phone queries may change as well as the keys within accounts.{name}.metadata. All future accounts will follow the same format as those documented below, with status and metadata keys, the latter being an object with its own account-specific properties. If a key does not exist within an account, it can be treated as the following:

"account_name": {
    "status": "unavailable",
    "metadata": {}
}

Account Statuses

The following statuses may be associated with any given account:

Note: only API v1 will return the account registration status as a string. API v2 will return the registration status in the following manner:

• true if the status equals "registered"
• false if the status equals "unregistered"
• null for all other statuses

null Data Type

There are many data fields that either return a value (such as string, boolean, integer, etc) or it may return null. We only provide the data we are able to obtain and are careful not to produce any false positives or false negatives. Therefore, if we are unable to make a conclusive decision about some data, we will return null. In the case of boolean fields, care should be taken that null values are handled distinctly from affirmatively false values.

Feedback

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