NAV Navbar
New logo

API Reference

Welcome to the Skopenow API. Access all of our API endpoints, such as our Person API which is used to identify Photos, Email addresses, Phone numbers, Occupations, Online personas, Behaviors, Locations, and Relationships. Additionally, our Company API (coming soon) can be used to look up company information related to an email, name, phone number, address, or a domain name.

We use a REST API, and all requests should be made over SSL. Additionally, all requests and responses, including errors, are encoded in JSON.

We also use specific language bindings to make integration as simple as possible. To view the different code snippets you can switch between the different language tabs.

Currently we support the following languages (adding shell, ruby, and python):

This API document will cover our Person API, Reverse API, filtering, inputs/output, scoring, erorr handling, authentication, and API replies. If you need further clarification, or are confused, or just want to talk - contact support@skopenow.com.

Authentication

You can authorize using the following code:

# With shell, you can pass the correct header with each request
curl "https://api.skopenow.com/v1/search" -H "x-api-key: API-KEY-HERE"
Install GuzzleHttp
http://docs.guzzlephp.org/en/latest/overview.html#installation
<?php
require 'vendor/autoload.php';

// Create a client to work with Skopenow API
$skopenow = new GuzzleHttp\Client(
    [
        'base_uri' => 'https://api.skopenow.com/v1/',
        'headers' => [
            'Content-Type' => 'application/json',
            'x-api-key' => 'API-KEY-HERE',
        ]
    ]
);
<?php
try {
  // Test authentication
  $response = $skopenow->get("search");
  echo $response->getBody();
} catch (\Exception $e) {
  // Failed
  echo $e->getMessage();
}
Install restler
https://www.npmjs.com/package/restler
var rest = require('restler');

var skopenow = new rest.Service({
  baseURL: 'https://api.skopenow.com/v1/',
  headers: {
            'Content-Type': 'application/json',
            'x-api-key': 'API-KEY-HERE',
        }
});
//Authentication Test
skopenow.get('search').on('success', function(data, response) {
  // Authenticated
  console.log(data);
}).on('error', function(err, response) {
  // Failed
  console.log(err);
});

Which will return the following:

{"code":200,"message":"Authenticated"}

Make sure that you replace API-KEY-HERE with your own API key (found in your settings page).

Your API key is needed in order to access Skopenow’s content. Your key can be generated from within your registered account’s account panel.

All API requests must include an API key within the header which should resemble the following format:

x-api-key: API-KEY-HERE

Errors

The Skopenow API returns standard HTTP success or error status codes. Errors codes will include additional about what went wrong. Our responses are encoded as JSON.

HTTP Status Codes

Here’s an example of a error response.

  {
    "error": {
      "code": "400",
      "message": "Your input is invalid"
    }
  }
Code Title Message
200 Success Authenticated.
400 Invalid Request Your input is invalid.
401 Unauthorized Insufficient credit or account has been deactivated.
403 Forbidden Your API key is wrong.
404 Not Found No results were returned for your search.
405 Bad Request Bad Request.
429 Rate Limit You’ve exceeded our rate limit!
500 Internal Server Error We are currently experiencing a problem with our server. Please try again later.
503 Service Unavailable We’re temporarily offline for maintenance. Please try again later.
800 Created The resource was asynchronously created.

All errors will be in form of JSON and contain a message.

Rate Limiting

Use the following call to check the status of your rate limit:

curl -i https://api.skopenow.com/v1/search -H "x-api-key: API-KEY-HERE"
<?php
try {
  // Test Limit
  $response = $skopenow->get("search");

  $limit = $response->getHeaderLine('X-RateLimit-Limit');
  $remaining = $response->getHeaderLine('X-RateLimit-Remaining');

} catch (\Exception $e) {
  // Failed
  echo $e->getMessage();
}
skopenow.get('search').on('success', function(data, response) {
  // Test Limit
  var limit = response.headers['x-ratelimit-limit'];
  var remaining = response.headers['x-ratelimit-remaining'];

}).on('error', function(err, response) {
  // Failed
  console.log(err);
});

Here’s an example of a rate limit response.

HTTP/1.1 200 OK
Content-Type: application/json
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 5
X-Quota-Limit: 49
X-Quota-Remaining: 35

{"code":200,"message":"Authenticated"}

Here’s an example of a rate limit error response.

HTTP/1.1 429 You have exceeded our rate limit
X-RateLimit-Limit: 5
X-RateLimit-Remaining: 0
X-Quota-Limit: 49
X-Quota-Remaining: 35
Content-Type: application/json

{"code":429,"message":"You have exceeded our rate limit"}

You are currently allowed to make 10 concurrent requests before you are rate limited. Check the returned HTTP headers of any API request to view your current rate limit status. Additionally, we include your current search quota within the HTTP header.

If you’re constantly running into this error or need a higher rate limit, email us at support@skopenow.com.

Header Name
X-RateLimit-Limit The maximum number of requests that the user is permitted to make per minute.
X-RateLimit-Remaining The number of requests remaining in the user’s rate limit window.
X-Quota-Limit The number of searches your account will permit without an overage charge.
X-Quota-Remaining The number of searches you have remaining before you are charged an overage fee.

If you are rate limited you will receive a 429 error indicating your status.

Versioning

When we make backwards incompatible changes to any of our APIs we will release new dated versions and alert you by email of the changes. Each API has a separate version which can be seen below. This same version table is also accessible from within your account settings.

You can change your API version by changing the version number /v1/ in the endpoint URL.

Any webhooks triggered will also use the request specified version.

API Current Version Date
Person API 1.0 1-1-2017
Reverse API 1.0 1-1-2017

Webhooks

The Person API can have an asynchronous response to requests (since there’s some complex background processing involved). For these types of requests - you can either poll the endpoint, or give us a webhook url that can be called when the request has finished processing.

You can pass along a webhook url query parameter along with each request.

To link your request with a webhook you can store the returned id when a request succeeds. When we perform the webhook response, it will contain the same requested id.

If we receive a return to the webook POST that does not have an HTTP 200 status - we will attempt to deliver the webhook up to 10 times with an exponential backoff.

Response POST Body

The incoming webhook POST request’s body looks like this:

{
  "id": "abCD-E12_3",
  "type": "json",
  "inputs": {
    ...
  },
  "status": 1,
  "score": 78.1234,
  "summary": {
    "locations": [
      {
        "value": "Oyster Bay, NY",
        "address": "1 Maple St, Oyster Bay, NY 11771",
        "lat": "40.6602154",
        "lng": "-73.9627918"
      },
      ...
    ],
    "phones": [
      {
        "value": "1(234) 567-8910"
      },
      ...
    ],
    "relatives": [
      {
        "value": "Robert James",
        "location": "New York, NY",
      },
      ...
    ],
    "emails": [
      {
        "value": "Robert@Skopenow.com"
      },
      ...
    ],
    "websites" :[
      {
        "value": "Skopenow.com"
      },
      ...
    ], 
    "nicknames": [
      "Rob",
      "Robert",
      ...
    ],
    "profiles": [
      {
        "value": "Robert.James",
        "source": "Facebook",
        "is_relative": 0,
        "url": "https://www.facebook.com/profile.php?id=100012978587094"
        "image": "https://scontent-iad3-1.xx.fbcdn.net/v/t1.0-1/p320x320/13895517_127244317718187_5039702033725309295_n.jpg?oh=bceed076afa2cc669eb5554fc2b1a539&oe=594789FA",
        "rank": 0,
        "result_index": 0
      },
      ...
    ]
  },
  "results": [
    {
      "source": "Facebook",
      "identifiers": ["Robert James","New York","1983","Possible Match"],
      "url": "https://www.facebook.com/profile.php?id=100012978587094",
      "ip": "1.2.3.4",
      "postdate": "12/31/2016",
      "details": {
        {
          "image": "https://s3-us-west-2.amazonaws.com/skopenow/1483478335586c153f2cf9e_screenshot.jpg",
          "thumb": "https://scontent.xx.fbcdn.net/v/t1.0-1/p160x160/13895517_127244317718187_5039702033725309295_n.jpg?oh=096b5b47a441e483889c1e7c4dddeb52&oe=58E75D65",
          "type": "about",
          "url": "https://www.facebook.com/profile.php?id=100012978587094/about"
        }
      },
      ...
    },
    ...
  ]
}

Each response will contain a body of text that includes your search data. The response contains an id, inputs, status, score, summary, and results.

Theid is a unique number used to identify the search - this number can be used to retrieve previous reports. The status, will reply with a 0 if the request has failed or a 1 if it has succeeded. The report score is used to evaluate the quality of the search - based on 1.0 scale. The inputs, will include the search inputs you entered. The summary will list phone numbers, addresses, emails, profile id’s, locations, websites, and nicknames. The results will contain source information such as identifiers, URLs, photo links, and post date.

Attribute Type Description
id string Report identifier (unique to each source)
type string In this case it contains json
status integer 0 for failure and 1 for success
inputs JSON Includes the search inputs you entered
score number Report score (used for relevance and accuracy)
summary JSON Report summary will contain phone numbers, addresses, emails, profile id’s, locations, websites, and nicknames.
results array Results will contain source information such as identifiers, URLs, photo links, and post date.

For testing webhooks, we recommend webhookinbox.com, which allows you to inspect arbitrary webhook requests.

The results attribute can be further broken down into the following data types:

Type Description
source The social media profile or website found
identifiers The variables used to identify the subject within the source
url The source’s URL
ip Server hosting the source’s content
postdate Diplays the date the content was created
details Includes image and thumbnail URLs, content type, and indexed page URLs.

PDF Webhook

Here is what the PDF data format should look like:

{
  "id": "abCD-E12_3",
  "type": "pdf",
  "file_name": "Robert_James_report-CWjpzvSpCN57MGUgJfpOuDsttIVW07DRZI7PlOjB6LQ.57cca151c2a1e.pdf",
  "url": "https://s3-us-west-2.amazonaws.com/skopenow-static/Analyst_files/Robert_James_report-CWjpzvSpCN57MGUgJfpOuDsttIVW07DRZI7PlOjB6LQ.57cca151c2a1e.pdf",
  "inputs": {
    ...
  }
}

Our PDF reports include a digital summary, screenshots, identifiers, metadata, contact information, and location data. Keep in mind that it may take up to 2 minutes to generate a 100 page PDF report (although most reports are less than 50 pages long). If you request a PDF output, the webhook will acknowledge the request and reply with your selection.

Attribute Type Description
id string Report identifiers (how we found this source)
type string In this case it contains pdf
file_name number PDF filename
url string Full PDF URL
inputs JSON Includes the search inputs you entered

Securing Webhooks

To validate a Skopenow webhook we suggest verifying the webhook payloads with the X-Request-Signature header (which is passed along with every webhook). If you’re using one of our client bindings to parse webhooks, say the Ruby library, we’ll do this for you.

Header Name
X-Request-Signature A SHA1 HMAC hexdigest computed with your API key and the raw body of the request.

Person API

Name and Location

The API response body looks like the following. Note that the person attributes can be empty if no data is found.

{
 "inputs": {
  ...
 },
 "filters": {
  ...
 },
 "output": {
  ...
 }
}
<?php
try {
  // Test Search
  $request = [
    "inputs" => [
      "name" => ["Robert James"],
      "location" => ["Oyster Bay, NY"]
    ],
    "output" => [
      "type" => "json",
      "destination" => "url",
      "url" => "http://requestb.in/123456"
    ]
  ];
  $response = $skopenow->post("search", ['json' => $request]);

  echo $response->getBody();

} catch (\Exception $e) {
  // Failed
  echo $e->getMessage();
}
curl -X POST -H "x-api-key: API-KEY-HERE" -H "Content-Type: application/json" -d '{
  "inputs" : {
     "name" : ["Robert James"],
     "location" : ["Oyster Bay, NY"]
  },
  "output" : {
     "type" : "json",
     "destination" : "url",
     "url": "http://requestb.in/123456"
  }
}' "https://api.skopenow.com/v1/search"
// Test Search
var request = {
  "inputs": {
    "name": ["Robert James"],
    "location": ["Oyster Bay, NY"]
  },
  "output": {
    "type": "json",
    "destination": "url",
    "url": "http://requestb.in/123456"
  }
};

skopenow.json("POST","search", request).on('success', function(data, response) {
  // Succeeded
  console.log(data)

}).on('error', function(err, response) {
  // Failed
  console.log(err);
});

The code above should return something like this:

{"code":800,"type":"direct","id":"abCD-E12_3"}

Skopenow’s Person API uses a name and location to conduct a search. To avoid making additional requests we allow you to build upon your search criteria. For instance, if additional inputs are used they will contribute to refining the results.

In order for the Person API to function properly, you will need to add at least one name and at least one location. In some cases you may have multiple names and multiple locations that you would like to use as inputs, which can be packaged together and sent as an array.

Combining inputs and building your own custom search will only count as one API call.

HTTP Request

POST https://api.skopenow.com/v1/search

Content type: application/json

Request Body

Each request is broken into three main categories, inputs, filters, and outputs. Inputs tell Skopenow what you want to search for, filters can be used to narrow or broaden a search, and outputs are used to describe the format and final destination of the search results.

Parameter Type Description
inputs JSON Search criteria (name, location, etc.)
filters JSON Added parameters to refine results
output JSON Output format and content destination

Since this is an asynchronous job, you will receive the report within a minute or two of the request. The inputs used and the output destination selected will have an effect on the time required to generate and deliver each report.

Attributes

The API response for the Person API’s required inputs looks like the this.

{
  "name": [...],
  "location": [...],
}

In order for the Person API to work name and location are required. If you do not know the name and location of your subject, check out the Reverse API.

In many cases you may want to include a nickname or additional name, and both current and past locations. This can be handled by passing an array through the name and location parameters.

Parameter Type Description
name array ex. [“John Smith” ,“Jonathan M. Smith”]
location array ex. [“Oyster bay, NY”,“NY, NY”]

You can use other inputs in addition to the name and location to expand or refine your search. If the data type is an array, it means we can accept multiple data points per parameter.

The API response for optional attributes.

{
  "address": [...],
  "phone": [...],
  "email": [...],
  "birthday": ["..."],
  "age": ["..."],
  "job": ["..."],
  "school": ["..."],
  "username": "XXXXX"
}
Parameter Type Description
address array ex. [“1 Maple St Brooklyn, NY 11225”]
phone array ex. [“(516) 330-5677”]
email array ex. [“Robert@skopenow.com” ,“Marc@skopenow.com”]
birthday array ex. [“mm/dd/yyyy” ,“mm/dd/yyyy”]
age array ex. [“18” ,“23”]
job array ex. [“Software Developer” ,“CEO”,“Photographer”]
school array ex. [“Vanderbilt University”, “Oyster Bay High School”]
username string ex. [“RobDouglas2016”] - Social media usernames

You must include at least a name and one location to perform a general search. However, you can run reverse lookups using a combination of phone, email, address, and usernames. If you need further refinement, attributes such as job, age, and school can be used to further narrow your results. Passing email, phone, address, or username will change your general search to a reverse search, which does not effect the number of API calls made.

Filters

The API response for filter settings looks like the this.

{
  "name": "exact",
  "location": "exact",
  "family": true,
  "exact": true,
  "hide": ["locations","relatives","phones"]
}

You can also use filter options to refine your report. While filters can be very helpful, they are not required. Skopenow’s filtering allows you to restrict certain profiles based on location and name specificity. You can also hide family profiles and report sections to simplify the output.

In many cases you won’t need to use filtering but with a common name like John Smith it can be very helpful. Additionally, if you are searching for an exact location rather than a state match, setting the location filter to 0 can be very helpful. If the location filter is set to 0, a profile that does not have an exact location match will be hidden. This setting is not recommended if you are searching for a unique name.

If you are searching a username such as Skopenow123 we will broaden our search to include the names and locations of the returned profiles. In other words, if facebook.com/Skopenow123 returns Robert Douglas New York, New York, we will search twitter for Robert Douglas, New York if twitter.com/Skopernow123 fails. If a name is included with your search, this functionality will work differently. You can turn this feature off by setting the exact filter to true.

Parameter Type Description
name string Use name match to restrict non-exact names. For example, Rob is a nickname of Robert, where as Rahb is a fuzzy name. You can use either [“exact”, “nickname”, “all”]. The default is all and nicknames will include fuzzy names.
location string Filter out profiles by location distance (in miles). The filter values are [“0”, “10”, “100”, “state”, “all”]. The default is all which will include all sources even those without a location listed.
family boolean When false, Skopenow will hide all of your subject’s family’s profiles. The default is true.
exact boolean You can narrow results by only showing exact input matches. This works well if you only want to see accounts with exact username, email, and phone number matches. The default is false, and will include results that deviate from a literal match.
hide array If you want to hide sections from your reports, you can specify them here. Report sections include [“summary”,“locations”,“nicknames”,“relatives”,“phones”,“emails”,“websites”,“profiles”,“metadata”,“score”,“urls”,“photos”,“tags”,“ip”]

Output

The API response for output settings looks like the this.

{
 "type" : "pdf",
 "destination" : "ftp",
 "ftp": {
    "host": "ftp.example.com",
    "port": 21,
    "username": "ftpuser",
    "password": "ftppassword",
 }
}

When an API request is made you will need to set an output type: json or pdf and a destination: url,ftp,email for your data.

Parameter Type Description
type string Select an output format: json or pdf
destination string A pdf can be sent via email, posted to a url, or uploaded via ftp while json format can only be sent to a specified url
url string Accept the json or pdf information via a webhook_url
email string Send the PDF report to a specific email address
ftp JSON Include FTP credentials for your PDF upload. The host, username, password are required while the port # is not. The default port is set to 21.

You can set a webhook_url when selecting to export to PDF. If you choose to receive the report via FTP you will be notified on the webhook with the pdf’sid,url, andnameonce the PDF finishes uploading. If you did not request to upload the report via FTP, you can use the PDF url returned on the webhook or receive the url via email.

Retrieving a Report

The command shown below will return JSON which has the same structure as the webhook return.

<?php
try {
  // Test Retrieve Report
  $response = $skopenow->get("search/abCD-E12_3");

  echo $response->getBody();

} catch (\Exception $e) {
  // Failed
  echo $e->getMessage();
}
curl "https://api.skopenow.com/v1/search/abCD-E12_3" -H "x-api-key: API-KEY-HERE"
// Test Retrieve Report
skopenow.get("search/abCD-E12_3").on('success', function(data, response) {
  // Succeeded
  console.log(data)

}).on('error', function(err, response) {
  // Failed
  console.log(err);
});

If you want to retrieve a JSON report that has already been generated, you can do this by using your reportid. You can also request a PDF via email using this same methodology.

This endpoint will retrieve a specific report by id.

HTTP Request

GET https://api.skopenow.com/v1/search

URL Parameters

Parameter Description
ID The report’s unique identifier used for retrieving reports.

Regenerate a Report

The API response body looks like the following. Note that the person attributes can be empty if no data is found.

{
 "filters": {
  ...
 },
 "output": {
  ...
 }
}
<?php
try {
  // Test Search
  $request = [
    "output" => [
      "type" => "json",
      "destination" => "url",
      "url" => "http://requestb.in/123456"
    ]
  ];
  $response = $skopenow->post("search/abCD-E12_3", ['json' => $request]);

  echo $response->getBody();

} catch (\Exception $e) {
  // Failed
  echo $e->getMessage();
}
curl -X POST -H "x-api-key: API-KEY-HERE" -H "Content-Type: application/json" -d '{
  "output" : {
     "type" : "json",
     "destination" : "url",
     "url": "http://requestb.in/123456"
  }
}' "https://api.skopenow.com/v1/search/abCD-E12_3"
// Test Search
var request = {
  "output": {
    "type": "json",
    "destination": "url",
    "url": "http://requestb.in/123456"
  }
};

skopenow.json("POST","search/abCD-E12_3", request).on('success', function(data, response) {
  // Succeeded
  console.log(data)

}).on('error', function(err, response) {
  // Failed
  console.log(err);
});

The code above should return something like this:

{"code":200,"id":"abCD-E12_3"}

You can also use the report id if you would like to view updated photo and profile content.

HTTP Request

POST https://api.skopenow.com/v1/search

Content type: application/json

URL Parameters

Parameter Description
ID The report’s unique identifier used for repeat requests.

Request Body

Each request is broken into two main categories, filters, and outputs. Filters can be used to narrow or broaden a search, and outputs are used to describe the format and final destination of the search results.

Parameter Type Description
filters JSON Added parameters to refine results
output JSON Output format and content destination

Since this is an asynchronous job, you will receive the report within a minute or two of the request. The inputs used and the output destination selected will have an effect on the time required to generate and deliver each report.

Reverse API

The API response for a reverse lookup.

<?php
try {
  // Test Reverse Search
  $request = [
    "inputs" => [
      "phone" => ["1234567890"],
    ],
    "output" => [
      "type" => "pdf",
      "destination" => "url",
      "url" => "http://requestb.in/123456"
    ]
  ];
  $response = $skopenow->post("search", ['json' => $request]);

  echo $response->getBody();

} catch (\Exception $e) {
  // Failed
  echo $e->getMessage();
}
curl -X POST -H "x-api-key: API-KEY-HERE" -H "Content-Type: application/json" -d '{
  "inputs" : {
     "phone" : ["12345678910"],
  },
  "output" : {
     "type" : "pdf",
     "destination" : "url",
     "url": "http://requestb.in/123456"
  }
}' "https://api.skopenow.com/v1/search"
// Test Reverse Search
var request = {
  "inputs": {
    "phone": ["12345678910"],
  },
  "output": {
    "type": "pdf",
    "destination": "url",
    "url": "http://requestb.in/123456"
  }
};

skopenow.json("POST","search", request).on('success', function(data, response) {
  // Succeeded
  console.log(data)

}).on('error', function(err, response) {
  // Failed
  console.log(err);
});

The reverse API can be used to find the social media profiles behind a phone number, email, username and address. Our phone, email, and username reverse are very useful when identifying associated social media profiles. If you combine a required reverse input such as phone and email, it will still only count as one API request.

We target exact matches, meaning we will find accounts registered with the input criteria and we will broaden our search to include sources that match additional variables that have been found during the search. For example, Robert@skopenow.com was used to register his LinkedIn page, but since this profile also shows ‘Oyster Bay’ as an identified location, we will search other social media profiles using 'Oyster Bay’ as a location filter. You can turn this feature off by setting the exact filter to true.

In some cases a single phone number, username, email, or address may have multiple known names and locations. In this case we will reply with an array of options. If you are unsure of who you are looking for - you can reply with not sure, or you can select the most likely name or location. If you have added a location such as 'New York’ but Skopenow replies with 'Oyster Bay’, selecting not sure will use 'New York’ as a location filter, but if you select 'Oyster Bay’ Skopenow will search both locations.

You can combine any of the attributes (name, location, age, job, etc.) with your phone, email, address, or username lookups to help refine your results.

Reverse lookup searches will include all of the same data shown in a general search report.

Address

The API response for an address lookup looks like the this.

{
 "inputs": {

    {
      "address": [...],
    }
 },
 "filters": {
  ...
 },
 "output": {
  ...
 }
}

Running a reverse address search can be done on residential and commercial properties. You will need to include a street name, city,state, zip code, and a street number.

The reverse address search requires anaddress as an input parameter.

Parameter Type Description
address array ex. [“1 Maple St, Oyster Bay, NY 11771”]

You can combine the reverse address search with any of the other Person API attributes.

Phone

The API response for an phone number lookup looks like the this.

{
 "inputs": {

    {
      "phone": [...],
    }
 },
 "filters": {
  ...
 },
 "output": {
  ...
 }
}

Running a reverse phone search can be done on cellular and landline phones. You will need to include a 10 digitphone number.

Parameter Type Description
phone array ex. [“1(234) 567-8910”]

You can combine the reverse phone search with any of the other Person API attributes.

Email

The API response for an email address lookup looks like the this.

{
 "inputs": {

    {
      "email": [...],
    }
 },
 "filters": {
  ...
 },
 "output": {
  ...
 }
}

Running a reverse email search can be done using a work, ISP (comcast, verizon, etc.), and personal (gmail, yahoo, etc.) email addresses.

Parameter Type Description
email array ex. [“Robert@skopenow.com” ,“Marc@skopenow.com”]

You can combine the reverse email search with any of the other Person API attributes.

Username

The API response for a username lookup looks like the this.

{
 "inputs": {

    {
      "username": "Robert.James"
    }
 },
 "filters": {
  ...
 },
 "output": {
  ...
 }
}

The reverse username search doesn’t really have many restrictions but requires and will accept any alphanumerical string. Usernames that are simple common names like “Rob” will not yield quality results and should be combined with additional attributes.

Usernames can include alphanumeric keys and should be longer than 3 letters in length. You can normally find social media usernames at the end of a specific URL. For example, within the URL facebook.com/Skopenow123, Skopenow123 is the designated username.

Parameter Type Description
username string ex. [“RobDouglas2016”] - Social media usernames

You can combine the reverse username search with any of the other Person API attributes.

Filters

The API response for an filter settings looks like the this.

{
  "name": "exact",
  "location": "exact",
  "family": true,
  "exact": true,
  "hide": ["locations","relatives","phones"]
}

You can also use filter options to refine your report. While filters can be very helpful, they are not required. Skopenow’s filtering allows you to restrict certain profiles based on location and name specificity. You can also hide family profiles and report sections to simplify the output.

In many cases you won’t need to use filtering but with a common name like John Smith it can be very helpful. Additionally, if you are searching for an exact location rather than a state match, setting the location filter to 0 can be very helpful. If the location filter is set to 0, a profile that does not have an exact location match will be hidden. This setting is not recommended if you are searching for a unique name.

If you are searching a username such as Skopenow123 we will broaden our search to include the names and locations of the returned profiles. In other words, if facebook.com/Skopenow123 returns Robert Douglas New York, New York, we will search twitter for Robert Douglas, New York if twitter.com/Skopernow123 fails. If a name is included with your search, this functionality will work differently. You can turn this feature off by setting the exact filter to true.

Parameter Type Description
name string Use name match to restrict non-exact names. For example, Rob is a nickname of Robert, where as Rahb is a fuzzy name. You can use either [“exact”, “nickname”, “all”]. The default is all and nicknames will include fuzzy names.
location string Filter out profiles by location distance (in miles). The filter values are [“0”, “10”, “100”, “state”, “all”]. The default is all which will include all sources even those without a location listed.
family boolean When false, Skopenow will hide all of your subject’s family’s profiles. The default is true.
exact boolean You can narrow results by only showing exact input matches. This works well if you only want to see accounts with exact username, email, and phone number matches. The default is false, and will include results that deviate from a literal match.
hide array If you want to hide sections from your reports, you can specify them here. Report sections include [“summary”,“locations”,“nicknames”,“relatives”,“phones”,“emails”,“websites”,“profiles”,“metadata”,“score”,“urls”,“photos”,“tags”,“ip”]

Attributes

You can use the following inputs in addition to email, phone, username, and address.

{
  "name": [...],
  "location": [...],
  "address": [...],
  "phone": [...],
  "email": [...],
  "birthday": ["..."],
  "age": ["..."],
  "job": ["..."],
  "school": ["..."],
  "username": "XXXXX"
}

You can use the same Person API attributes to enhance your reverse search.

Parameter Type Description
name array ex. [“Robert James” ,“Rob M. James”]
location array ex. [“Oyster bay, NY”]
address array ex. [“1 Maple St, Oyster Bay, NY 11771”]
phone array ex. [“1(234) 567-8910”]
email array ex. [“Robert@skopenow.com” ,“Marc@skopenow.com”]
birthday array ex. [“mm/dd/yyyy” ,“mm/dd/yyyy”]
age array ex. [“18” ,“23”]
job array ex. [“Software Developer” ,“CEO”,“Photographer”]
school array ex. [“Vanderbilt University”, “Oyster Bay High School”]
username string ex. [“RobDouglas2016”] - Social media usernames

Combining attributes with reverse inputs will only count as one API call.

Return

The Skopenow API will reply with a suggestion list if more than one person matches the search criteria.

{
  "code": 200,
  "type": "reverse",
  "suggestions": [
    {
      "first_name": "Robert",
      "middle_name": "M",
      "last_name": "James",
      "birth_year": 1983,
      "relatives": [
        {
          "first_name": "Kim",
          "middle_name": "K",
          "last_name": "James",
          "city": "",
          "state": "",
          "address": "",
          "zip": "",
          "birth_year": 1960
        },
        ...
      ],
      "addresses": [
        {
          "address": "1 Maple St, Oyster Bay, NY",
          "city": "Oyster Bay, NY",
          "state": "NY",
          "zip": "11771"
        },
        ...
      ],
      "emails": [
        "Robert@skopenow.com",
        ...
      ],
      "other_names": [
        {
          "first_name": "Bobby",
          "middle_name": "",
          "last_name": "James"
        },
        ...
      ],
      "phones": [
        "1(234) 567-8910",
        ...
      ],
      "suggestion_key": "y6QKDtuRqfLeCXP2fOM0NuTH"
    },
    ...
  }
}

In many cases your search criteria will produce ambiguous results. For instance, a landline phone may have been registered to more than one homeowner. Additionally, there may be more than one individual living at a specific address. We have also seen the same email address return registered accounts with two different names.

To avoid undesired results, Skopenow will provide a list of options associated with a uniquesuggestion_key. The suggestion_keyshould be used to make select the correct profile.

If you are unsure of who you are looking for you can select not sure, or you can select the most likely name or location. If you have added a location such as 'New York’ but Skopenow replies with a different city like 'Oyster Bay’, selecting not sure will use 'New York’ as the location filter. However, if you select 'Oyster Bay’ Skopenow will use both, the input and suggested location. Thenot sureoption will also have it’s ownsuggestion_key.

Parameter Type Description
suggestion_key string Use the unique identifier to make a selection based on the returned list.

Eachsuggestion_keyrepresents a profile that contains the data shown below.

Attribute Type Description
first_name string First name
middle_name string Middle name
last_name string Last name
other_names array Alias (alternate names)
birth_year number Birth year (age also)
relatives array Family members
addresses array Associated locations
emails array Possible emails
phones array Landlines or Cellphones
suggestion_key string Each suggestion will include a unique identifier key which can be used to make a selection.

When the Skopenow API returns multiple suggestions the data will be returned asynchronously with an800code.

To select a given profile use the suggestion key.

{
 "inputs": {

    {
      "suggestion_key": "y6QKDtuRqfLeCXP2fOM0NuTH"
    }
 },
 "filters": {
  ...
 },
 "output": {
  ...
 }
}

Scoring

Skopenow will return two types of scores, one per result and one per report. The report score depends on many different factors but heavily considers the number of results, uniqueness of name, type of city (big or small), social media profiles, address history, and known relatives when evaluating a score. The report score is used to evaluate the quality of the search and is scored on a 1.0 scale. Skopenow will not charge charge for a search that receives a score less than a .5.

When scoring each source, Skopenow evaluates key identifiers (for accuracy), site rank, quantity of results, and content (for quality). We use the result score to sort and rank each result found.

You can build your own filtering to display results that only show a score minimum score.