NAV Navbar
New logo

API Reference

Welcome to Skopenow’s API documentation. With our API you can access all of our API endpoints, such as our Person and Business intelligence API. Our person search is great for findings social media profiles, contact data, relationships, relatives, court records, and analyzing behaviors. Our business search provides social media pages, ratings and reviews, ownerships details, addresses, contact info, court records, and employee information.

We use a REST API, and all requests must be submitted through SSL. Additionally, all requests and responses, including errors, are encoded in JSON.

We 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, Business API, Reverse API, filtering, inputs/output, scoring, error handling, authentication, and API replies. If you need further clarification, 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 API key (found in your settings page).

Your API key is needed 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 an 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 the 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 backward 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
Business API 1.0 10-31-2019
Person API 1.0 1-1-2017
Reverse API 1.0 1-1-2017

Webhooks

The Person and Business API can have an asynchronous response (since there’s 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 webhook POST that does not have an HTTP 200 status - we will attempt to deliver the webhook up to 10 times with exponential backoff.

Response Person 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": [
      {
         "is_current": true,
          "value": "New York, NY",
          "lat": 40.7539222,
          "lng": -73.9676663,
          "address": "333 E 49th St Apt 2r, New York, NY",
          "result_index": -1,
          "is_association": true,
      },
          ],
    "phones": [
      {
        "value": "1(234) 567-8910",
        "result_index": -1,
        "is_association": true,
      },
      ...
    ],
    "relatives": [
      {
        "value": "Kim K Douglas",
        "location": null,
        "result_index": -1,
        "is_association": true,
      },
      ...
    ],
    "emails": [
      {
        "value": "Robert@Skopenow.com",
        "is_association": false,
      },
      ...
    ],
    "websites" :[
      {
        "value": "Skopenow.com",
        "is_association": true,

      },
      ...
    ],
    "job": [
      {
        "position": "CEO",
        "company": "Skopenow",
        "start_date": 2015,
        "end_date": current,
        "result_index": 8,
        "is_association": true,

      },
      ...
    ],
    "schools": [
      {
        "value": "Vanderbilt University",
        "start_date": 2006,
        "end_date": 2010,
        "result_index": 8,
        "is_association": false,
      },
      ...
    ],
    "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": [
    {
      "id" : "PLp-Zhk7hIpHw121"
      "source": "Facebook",
      "identifiers": ["Robert James","New York","1983","Possible Match"],
      "identifiers_details": [
        {
            "type": "name",
            "value": "Robert James",
        },
        {
            "type": "work",
            "value": "Skopenow",
        }
      ],
      "keywords": [
          {
              "matched": "Skopenow",
              "type": "work",
              "value": "skopenow"
          }
      ],
      "url": "https://www.facebook.com/profile.php?id=100012978587094",
      "ip": "1.2.3.4",
      "postdate": "12/31/2016",
      "confidence": "exact",
      "is_file": 0,
      "is_profile": 1,
      "is_relative": 0,
      "is_association": 0,
      "details": [
        {
          "result_type": "result",
          "id": "PLp-Zhk7hIpHwqUV123",
          "image": "https://s3-us-west-2.amazonaws.com/skopenow/1483478335586c153f2cf9e_screenshot.jpg",
          "type": "Photos Liked",
          "url": "https://www.facebook.com/photo.php?fbid=2146543745412756",
          "category": "Social media profile",
          "tags": ["food", "people", "coffee", "table"],
          "keywords": [
            {
              "matched": "Skopenow",
              "type": "work",
              "value": "skopenow"
            }
          ],
          "download_link": "https://s3-us-west-2.amazonaws.co...."
        }
      ],
      ...
    },
    ...
  ],
  "associations": [
      //in case of association report
    {
        "id": "dH40XDIdAhaGhi4SaZHZanYc3FOXjLB3Lusu0nP6cDCElficvTtVQ2QrxAio7V1-7UevUP6vy7mufrBxUjppKt48uN_FLq5rloCYTdZwRi62jr-2z4FyRIrxoiSCjmDbKP-b7WCRy69nfFydPAWAUAEcG7GmYWLIzdbvg2zxE1E",
        "source": "Facebook",
        "identifiers": null,
        "identifiers_details": [
            {
                "type": "insite",
                "value": "Connected To: Crunchbase",
                "related_result_id": 12345,
                "related_source": "crunchbase"
            },
            {
                "value": "Oyster Bay, NY",
                "type": "location"
            },
            {
                "value": "Skopenow",
                "type": "work"
            },
            {
                "value": "Rob Douglas",
                "type": "name"
            },
            {
                "type": "score",
                "value": "Positive Match"
            }
        ],
        "keywords": [],
        "behaviors": [],
        "categories": null,
        "url": "https://www.facebook.com/rob.douglas.7923",
        "ip": null,
        "postdate": 1557830993,
        "confidence": "exact",
        "is_file": 0,
        "is_profile": 1,
        "is_relative": 0,
        "is_association": 1,
        "details": [
            {
                "result_type": "result",
                "id": "dH40XDIdAhaGhi4SaZHZanYc3FOXjLB3Lusu0nP6cDCElficvTtVQ2QrxAio7V1-7UevUP6vy7mufrBxUjppKt48uN_FLq5rloCYTdZwRi62jr-2z4FyRIrxoiSCjmDbKP-b7WCRy69nfFydPAWAUAEcG7GmYWLIzdbvg2zxE1E",
                "image": "https://scontent.xx.fbcdn.net/v/t1.0-1/c170.50.621.621a/s200x200/602480_10100110010210498_1105520697_n.jpg?_nc_cat=106&_nc_ht=scontent.xx&oh=9372b9df69afd1f8b1db38311b347da2&oe=5D583F74",
                "type": "result",
                "url": "https://www.facebook.com/rob.douglas.7923",
                "category": "Social media profile",
                "tags": [],
                "keywords": [],
                "behaviors": [],
                "categories": null,
                "download_link": ""
            }
        ]
    },
    ...
  ],
}

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 a 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 Displays the date the content was created
details Includes image and thumbnail URLs, content type, and indexed page URLs.

Response Business 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": [
      {
       "is_current": true,
        "value": "New York, NY",
        "lat": 40.7539222,
        "lng": -73.9676663,
        "address": "333 E 49th St Apt 2r, New York, NY",
        "result_index": -1
        "is_association": true,
      },
      ...
    ],
    "phones": [
      {
        "value": "1(234) 567-8910",
        "result_index": -1,
        "is_association": true,
      },
      ...
    ],
    "owners": [
      {
        "flags": 268632224,
        "hash": "9212553bea74076705f74bfd9f6dada2",
        "type": "owners",
        "url": "https://www.crunchbase.com/person/robert-douglas-2",
        "id": 24555296,
        "source": "crunchbase",
        "name": "Robert Douglas",
        "serial": 0,
        "key": "fd21766cb4e8271bbf4eca6fa2875f3d",
        "index": 6,
        "image": null
      }
      ...
    ],
    "emails": [
      {
        "value": "info@skopenow.com",
        "is_association": false,
        "result_index": 2
      },
      {
        "value": "rob@skopenow.com",
        "is_association": true,
        "result_index": 3
      },
      ...
    ],
    "websites" :[
      {
          "value": "Skopenow.com",
          "result_index": 6
      },
        ...
    ],
     "relatives": [
      //in case of an association search
      {
          "value": "Kim K Douglas",
          "location": null,
          "result_index": -1,
          "is_association": true,

      },
      ...
    ],

    "job": [
      //in case of an association search
      {
        "position": "Management Development Program",
        "company": "M&T Bank",
        "start_date": 2007,
        "end_date": 2008,
        "result_index": 8,
        "is_association": true,

      },
      ...
    ],
    "schools": [
      //in case of an association search
      {
        "value": "Baruch College, Zicklin School of Business",
        "start_date": 2009,
        "end_date": 2011,
        "result_index": 8,
        "is_association": true,

      },
      ...
    ],
    "nicknames": [
      "skope",
      ...
    ],
    "company_details": [
      {
        "name": "Skopenow",
        "flags": 123456,
        "hash": "a0f9987db8a64d5bd8008d6da17cc193",
        "parent_comb": 24555462,
        "type": "company_details",
        "assoc_profile": "comb_base",
        "id": 123456,
        "founded": null,
        "description": "Skopenow's platform identifies, collects, and analyzes public information on people and businesses by scouring millions of sources and data points.  While Skopenow is built for use in insurance, government, and law,  the product is also highly applicable in HR, real estate, and education.",
        "key": "2d17e487285c6f46a19a5f3fbde4ef78",
        "matched_results_ids": "",
        "index": 2,
        "incorporation_date": null,
        "state_incorporated": null,
        "company_size": null,
        "duns": null,
        "business_type": null,
        "market_cap": null,
        "stock_ticker": null,
        "hours_of_opertaion": null,
        "money_raised": null,
        "revenue": null
      },
      ...
    ],
    "profiles": [
      {
        "is_top_profile": 1,
        "value": "Rob Douglas",
        "source": "Facebook",
        "is_relative": 0,
        "url": "https://www.facebook.com/rob.douglas.7923",
        "image": "https://scontent.xx.fbcdn.net/v/t1.0-1/c170.50.621.621a/s200x200/602480_10100110010210498_1105520697_n.jpg?_nc_cat=106&_nc_ht=scontent.xx&oh=9372b9df69afd1f8b1db38311b347da2&oe=5D583F74",
        "rank": 0,
        "result_index": 0
        },
        ...
    ],
    "rating": [
      {
        "id": 123456,
        "input_flags": 3,
        "flags": 1234568,
        "hash": "0e0f671bb271df7cf9ffcce4ccaae4f1",
        "type": "rating",
        "source": "bbb",
        "rating": "A+",
        "serial": 0,
        "key": "141f93e49749f69443b6d2f427b0e587",
        "index": 5,
        "url": "",
        "reviews": ""
      }
    ],
  },
  "results": [
    {
      "id" : "PLp-Zhk7hIpHw121"
      "source": "Facebook",
      "identifiers": ["Robert James","New York","1983","Possible Match"],
      "identifiers_details": [
        {
            "type": "name",
            "value": "Robert James",
        },
        {
            "type": "work",
            "value": "Skopenow",
        }
      ],
      "keywords": [
        {
            "matched": "Skopenow",
            "type": "work",
            "value": "skopenow"
        }
      ],
      "url": "https://www.facebook.com/profile.php?id=100012978587094",
      "ip": "1.2.3.4",
      "postdate": "12/31/2016",
      "confidence": "exact",
      "is_file": 0,
      "is_profile": 1,
      "is_relative": 0,
      "is_association": 0,
      "details": [
        {
          "result_type": "result",
          "id": "PLp-Zhk7hIpHwqUV123",
          "image": "https://s3-us-west-2.amazonaws.com/skopenow/1483478335586c153f2cf9e_screenshot.jpg",
          "type": "Photos Liked",
          "url": "https://www.facebook.com/photo.php?fbid=2146543745412756",
          "category": "Social media profile",
          "tags": ["food", "people", "coffee", "table"],
          "keywords": [
            {
              "matched": "Skopenow",
              "type": "work",
              "value": "skopenow"
            }
          ],
          "download_link": "https://s3-us-west-2.amazonaws.co...."
        }
      ],
      ...
    },
    ...
  ],
  "associations": [
    {
      "id": "dH40XDIdAhaGhi4SaZHZanYc3FOXjLB3Lusu0nP6cDCElficvTtVQ2QrxAio7V1-7UevUP6vy7mufrBxUjppKt48uN_FLq5rloCYTdZwRi62jr-2z4FyRIrxoiSCjmDbKP-b7WCRy69nfFydPAWAUAEcG7GmYWLIzdbvg2zxE1E",
      "source": "Facebook",
      "identifiers": null,
      "identifiers_details": [
        {
            "type": "insite",
            "value": "Connected To: Crunchbase",
            "related_result_id": 12345,
            "related_source": "crunchbase"
        },
        {
            "value": "Oyster Bay, NY",
            "type": "location"
        },
        {
            "value": "Skopenow",
            "type": "work"
        },
        {
            "value": "Rob Douglas",
            "type": "name"
        },
        {
            "type": "score",
            "value": "Positive Match"
        }
      ],
      "keywords": [],
      "behaviors": [],
      "categories": null,
      "url": "https://www.facebook.com/rob.douglas.7923",
      "ip": null,
      "postdate": 1557830993,
      "confidence": "exact",
      "is_file": 0,
      "is_profile": 1,
      "is_relative": 0,
      "is_association": 1,
      "details": [
        {
            "result_type": "result",
            "id": "dH40XDIdAhaGhi4SaZHZanYc3FOXjLB3Lusu0nP6cDCElficvTtVQ2QrxAio7V1-7UevUP6vy7mufrBxUjppKt48uN_FLq5rloCYTdZwRi62jr-2z4FyRIrxoiSCjmDbKP-b7WCRy69nfFydPAWAUAEcG7GmYWLIzdbvg2zxE1E",
            "image": "https://scontent.xx.fbcdn.net/v/t1.0-1/c170.50.621.621a/s200x200/602480_10100110010210498_1105520697_n.jpg?_nc_cat=106&_nc_ht=scontent.xx&oh=9372b9df69afd1f8b1db38311b347da2&oe=5D583F74",
            "type": "result",
            "url": "https://www.facebook.com/rob.douglas.7923",
            "category": "Social media profile",
            "tags": [],
            "keywords": [],
            "behaviors": [],
            "categories": null,
            "download_link": ""
        }
      ]
    },
    ...
  ],
  "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
      "id": "ClKI2-_v1eNJqX_oBFVPM0VjfIuonMCe9f-7ysnZkcyGHcRuHjikItiyPMhATw3FBg8Iv99EJ6cvW6Dh2Vuj6yaYu-d3BdE0KUi78RgZcR0VOkJS9yrYUPxaB9IwFIcwFh0MYkDIqxHjqcvEg15XUl94yWwx66rvIBKgKBaoR-M",
      "source": "Twitter",
      "identifiers": null,
      "identifiers_details": [
        {
            "type": "image",
            "value": "Image Match",
            "related_result_id": 12345
            "related_source": "facebook"
        },
        {
            "type": "score",
            "value": "Positive Match"
        }
      ],
      "keywords": [],
      "behaviors": [],
      "categories": null,
      "url": "https://twitter.com/Skopenow",
      "ip": null,
      "postdate": 1566739617,
      "confidence": "exact",
      "is_file": 0,
      "is_profile": 1,
      "is_relative": 0,
      "is_association": 0,
      "details": [
        {
            "result_type": "result",
            "id": "ClKI2-_v1eNJqX_oBFVPM0VjfIuonMCe9f-7ysnZkcyGHcRuHjikItiyPMhATw3FBg8Iv99EJ6cvW6Dh2Vuj6yaYu-d3BdE0KUi78RgZcR0VOkJS9yrYUPxaB9IwFIcwFh0MYkDIqxHjqcvEg15XUl94yWwx66rvIBKgKBaoR-M",
            "image": "https://pbs.twimg.com/profile_images/1103749278290399233/6iLvdnbH_400x400.png",
            "type": "profile",
            "url": "https://twitter.com/Skopenow",
            "category": "Social media profile",
            "tags": [],
            "keywords": [],
            "behaviors": [],
            "categories": null,
            "download_link": ""
        }
      ]
    },
    ...
  ],
}

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

Business API

Name and Location

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

{
 "inputs": {
  ...
 },
 "filters": {
  ...
 },
 "output": {
  ...
 }
}
<?php
try {

  $request = [
    "inputs" => [
      "name" => ["Skopenow"],
      "location" => ["Oyster Bay, NY"]
    ],
    "output" => [
      "type" => "json",
      "destination" => "url",
      "url" => "http://api.webhookinbox.com/i/123456/in/"
      "logo_url" => "https://www.skopenow.com/images/new_logo.png",
      "company_name" => "Skopenow",
    ]
  ];
  $response = $skopenow->post("business", ['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" : ["Skopenow"],
     "location" : ["Oyster Bay, NY"]
  },
  "output" : {
     "type" : "json",
     "destination" : "url",
     "url": "http://api.webhookinbox.com/i/123456/in/",
     "logo_url" : "https://www.skopenow.com/images/new_logo.png",
    "company_name" : "Skopenow",
  }
}' "https://api.skopenow.com/v1/search"
var request = {
  "inputs": {
    "name": ["Skopenow"],
    "location": ["Oyster Bay, NY"]
  },
  "output": {
    "type": "json",
    "destination": "url",
    "url": "http://api.webhookinbox.com/i/123456/in/",
    "logo_url" : "https://www.skopenow.com/images/new_logo.png",
    "company_name" : "Skopenow",
  }
};

skopenow.json("POST","business", 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 Business Search API uses a name and location to run. To avoid making additional requests we allow you to build upon your search criteria. For instance, if additional inputs are used they will help refine the results.

For the Business 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. Keep in mind that you can also run the business search using reverse parameters like domain and FEIN but within this section we will focus on name and location.

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

HTTP Request

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

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
logo_url STRING your company logo,
company_name STRING “your company name”,

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 affect the time required to generate and deliver each report.

Attributes

The API request for the Business API’s required inputs looks like this.

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

For the Business 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. [“Skopenow ”]
location array ex. [“New York, NY”,“Garden City, 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 optional inputs for the Business API look like the following:

{
  name:[...],
  location:[...],
  address:[...],
  phone:[...],
  email:[...],
  username:[...],
  keyword:[...],
  behaviors:[...],
  domain:[...],
  formed:[...],
  associate_name:[...],
  associate_location:[...],
  search_specificity:[...],
  custom_fields:[...],
  incident:XXX,
  fein:XXXX,
  claim:"XXX",
  "suggestion_key": "..." ,
}
Parameter Type Description
name array ex. [“Skopenow”]
location array ex. [“New York”]
address array ex. [“12 East 49th, NY 10017”]
phone array ex. [“(800) 252-1437”]
email array ex. [“Skopenow.com” ,“Onelookup.com”]
username array ex. [“skopenow”] - Social media usernames
keyword array ex. [“fraud”, “events”, “bankruptcy”]
behaviors array ex. [“Bad Reviews”, “Complaints”] company flags
domain array ex. [“http://www.skopenow.com”] - company website(s) domain
formed array ex. [“mm/dd/yyyy” ,“mm/dd/yyyy”]
associate_name array ex. [“Robert James”]
associate_location array ex. [“Oyster Bay, NY”]
search_specificity array ex. [“all”]
custom_fields object ex. {“field_name”:“value”}
incident string ex. Slip and fall
fein string ex. 12-3456789
claim string ex. 121454e
suggestion_key string ex. “abscd12345ww”

Example inputs with optional and required fields:

{
  "name": ["Skopenow"],
  "location": ["New York, NY"],
  "email": ["info@skopenow.com"]
}

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, domain, FEIN, and usernames. If you need further refinement, attributes such as associate_name, associate_location, and formed can be used to further narrow your results. Passing email, keyword, behavior, phone, address, or FEIN will change your general search to a reverse search, which does not affect the number of API calls made.

Filters

The filters for the Business API are as follows:

{
  "name": "exact",
  "location": "exact",
  "associate": true,
  "exact": true,
  "hide": ["rating", "associates", "company_details", "locations"]
}

Example Business API Post JSON body with inputs and filters (outputs field is excluded for example purposes but is required)

{
    "inputs": {
        "name": ["Skopenow"],
        "location": ["New York, NY"],
        "email": ["info@skopenow.com"]
    },
    "filters": {
        "name": "exact",
        "location": "0",
        "exact": true
    }
}

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, name, and confidence score. You can also hide or modify the owners’ profiles to simplify the output.

In many cases, you won’t need to use filtering; however, with a common name like Big Company, Inc., 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 using a username such as SkopenowFan1, we will include the names and locations of the returned profiles. In other words, if facebook.com/Skopenow123 returns Skopenow Corporation, New York, we will search twitter for Skopenow, New York in the event twitter.com/Skopenow123 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, Skopenow is a nickname of Skopenow Inc, so Skopenow is a fuzzy name match. 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 [“all”, “exct-sm”, “exct-bg”, “state”]. The default is all which will include all sources even those without a location listed.
associate boolean When false, Skopenow will hide all of your subject’s owners profiles. The default is true.
exact boolean You can narrow results by showing exact input matches. This works well if you only want to see accounts with an 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”,“associates”,“phones”,“emails”,“websites”,“profiles”,“metadata”,“score”,“urls”,“photos”,“tags”,“ip”, ,“company_details”,“owners”,“rating”].

Output

The output settings for the Business API look like this:

{
 "type" : "pdf",
 "destination" : "ftp",
 "logo_url" : "https://www.skopenow.com/images/new_logo.png",
"company_name" : "Skopenow",
 "ftp": {
    "host": "ftp.example.com",
    "port": 21,
    "username": "ftpuser",
    "password": "ftppassword",
 }
}

Example Business API Post JSON body with inputs and output settings set

{
    "inputs": {
        "name": ["Skopenow"],
        "location": ["New York, NY"],
        "email": ["info@skopenow.com"]
    },
    "outputs": {
        "type" : "pdf",
        "destination" : "ftp",
        "logo_url" : "https://www.skopenow.com/images/new_logo.png",
        "company_name": "Skopenow",
        "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
logo_url string your company logo,
company_name string your company name,
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, and name once 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
// Test Retrieve Report
try {
  $response = $skopenow->post("search/abCD-E12_3", ['json' => $request]);

  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/{id}

URL Parameters

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

Regenerate a Report

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

{
 "filters": {
  ...
 },
 "output": {
  ...
 }
}
<?php
try {

  $request = [
    "output" => [
      "type" => "json",
      "destination" => "url",
      "logo_url" => "https://www.skopenow.com/images/new_logo.png",
      "company_name" => "Skopenow",
      "url" => "http://api.webhookinbox.com/i/123456/in/"
    ]
  ];
  $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",
     "logo_url" : "https://www.skopenow.com/images/new_logo.png",
     "company_name" : "Skopenow",
     "url": "http://api.webhookinbox.com/i/123456/in/"
  }
}' "https://api.skopenow.com/v1/search/abCD-E12_3"
var request = {
  "output": {
    "type": "json",
    "destination": "url",
    "logo_url" : "https://www.skopenow.com/images/new_logo.png",
    "company_name" : "Skopenow",
    "url": "http://api.webhookinbox.com/i/123456/in/"
  }
};

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/{id}

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.

Extract Data

This is a new feature that allows you to request additional information from a specific source. You can request additional parameters using date and content type.

<?php
try {
  // extract request
  $request = [
    "extract_data" => [
    "date_before" => "11/22/2017",
    "date_after" => "11/14/2018",
    "extract_types" => ["photos_by","photos_interacted"],
    "source" => "facebook",
    "url" => "https://www.facebook.com/rob.douglas.7923",
    "result_id" => "y6QKDtuRqfLeCXP2-fOM0NuTH_",
    ],
  ];
  $response = $skopenow->post("result/extract/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 '{
  extract_data" : {
    "date_before": "11/22/2017",
    "date_after": "11/14/2018",
    "extract_types": ["photos_by","photos_interacted"],
    "source": "facebook",
    "url": "https://www.facebook.com/rob.douglas.7923",
    "result_id": "y6QKDtuRqfLeCXP2-fOM0NuTH_",
  }
}' "https://api.skopenow.com/v1/result/extract/abCD-E12_3"
var request = {
  "extract_data" : {
    "date_before": "11/22/2017",
    "date_after": "11/14/2018",
    "extract_types": ["photos_by","photos_interacted"],
    "source": "facebook",
    "url": "https://www.facebook.com/rob.douglas.7923",
    "result_id": "y6QKDtuRqfLeCXP2-fOM0NuTH_",
  }
};

skopenow.json("POST","result/extract/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"}

HTTP Request

POST https://api.skopenow.com/v1/result/extract/{id}/

Content type: application/json

URL Parameters

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

Request Body

When an extraction API request is made you will need to set the following parameters for the source value: Facebook or Twitter or Instagram or Youtube or Linkedin.

Parameter Type Description
date_before date ex. “11/22/2017”
date_after date ex. “11/14/2018”
extract_types array ex. [“photos_by”,“photos_interacted”,…] the table below shows each source and its extraction data types
url string ex. “https://www.facebook.com/rob.douglas.7923”
result_id string ex. “y6QKDtuRqfLeCXP2-fOM0NuTH_”

Sources and Data Types

Each source has a data type of either Pages, or Content. The following tables show each source and its types

Facebook

Type name Content Requires Date Description
All content true All Content (delayed process)
photos_in content true Photos In
photos_of content true Photos Of
photos_tagged_in content true Photos Tagged In
photos_by content true Photos by
photos_about content true Photos About
photos_commented content true Photos Commented On
stories_by content true Stories By
stories_in content true Stories In
stories_commented content true Stories Commented
stories_liked content true Stories Liked
stories_tagged content true Stories Tagged
Stories content true Stories Media Tagged
videos_commented content true Videos Commented
videos_by content true Videos By
videos_tagged content true Videos Tagged
videos_liked content true Videos Liked
Pages content false All
page_videos content false Videos
page_reviews content false Reviews
page_community content false Community
page_photos content false Photos
page_about content false About
page_locations content false Locations
page_music content false Music
page_posts content false Posts
page_events content false Events

Twitter

Type name Content Requires Date Description
all content false All Content (delayed process)
tweets content true Subject’s Tweets
tweeted content true Tweeted at Subject
media content true Subject’s Media
photos_by_subject content true Photos by Subject
photos_of_subject content true Photos of Subject
videos_by_subject content true Videos by Subject
videos_of_subject content true Videos of Subject
news content false News
hashtags content false Hashtags
all pages false Pages
tw_followers pages true Followers
tw_following pages true Following
likes pages true Likes

Instagram

Type name Content Requires Date Description
all content false All Content (delayed response)
photos content true Subject’s photos
insta_screenshots content true Subject’s Screenshots
insta_videos content true Subject’s Videos
insta_following content true Following
insta_followers content true Followers
insta_tags content true Tags

Youtube

Type name Content Requires Date Description
all false pages Pages
videos false pages Videos
playlists_page false pages Playlist
community false pages community
channels_page false pages Channels
discussion false pages Discussion

LinkedIn

Type name Content Requires Date Description
all content false All Content
company_current_employees content true Current Employees
mentions content false Subject’s Mentions
company_former_employees content true Former Employees

Yelp

Type name Content Requires Date Description
all content false All Content
business_photos content true Business Photos
business_reviews content false Business Reviews

Meetup

Type name Content Requires Date Description
all content false All Content
members content true Members
photos content true Photos
discussions content true Discussions
upcoming_events content true Upcoming Events
past_events content true Past Events
proposed_events content true Proposed Events
cancelled_events content true Cancelled Events

TripAdvisor

Type name Content Requires Date Description
all content false All Content
reviews content true Reviews

The code request should return something like this:

Regenerate a Screenshot

The following requests will allow you to recapture a screenshot that was DOA.

<?php
try {
  // Recapture request
  $request = [
    "recapture_data" => [
      "result_id" => "y6QKDtuRqfLeCXP2-fOM0NuTH_",
    ],
  ];
  $response = $skopenow->post("result/screenshot/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 '{
  "recapture_data" : {
    "result_id":"y6QKDtuRqfLeCXP2-fOM0NuTH_",
  }
}' "https://api.skopenow.com/v1/result/screenshot/abCD-E12_3"
var request = {
  "recapture_data" : {
    "result_id":"y6QKDtuRqfLeCXP2-fOM0NuTH_",
  }
};

skopenow.json("POST","result/extract/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"}

HTTP Request

POST https://api.skopenow.com/v1/result/screenshot/{id}

Content type: application/json

URL Parameters

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

Request Body

When an API request is made you will need to set the following parameters:

Parameter Type Description
result_id string ex. “y6QKDtuRqfLeCXP2-fOM0NuTH_”

The code request should return something like this:

Add Results Manually

The following requests allow you to manually add results to your report. The parameters required are url, rank,identifiers,source, and title. The rank parameter will dictate where in the report the added item will appear.

<?php
try {
  // Source request
  $request = [
    "source_data" => [
    "identifiers" => ["Rob Douglas"],
    "rank" => "1",
    "assoc" => false,
    "source" => "facebook",
    "title" => "Rob Douglas",
    "url" => "https://www.facebook.com/rob.douglas.7923",
    ]
  ];
  $response = $skopenow->post("result/add/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 '{
  "source_data" : {
    "identifiers":["Rob Douglas"],
    "rank":"1",
    "assoc" => false,
    "source":"facebook",
    "title":"Rob Douglas",
    "url":"https://www.facebook.com/rob.douglas.7923",
}
}' "https://api.skopenow.com/v1/result/add/abCD-E12_3"
var request = {
  "source_data" : {
    "identifiers":["Rob Douglas"],
    "rank":"1",
    "assoc" => false,
    "source":"facebook",
    "title":"Rob Douglas",
    "url":"https://www.facebook.com/rob.douglas.7923",
  }
};

skopenow.json("POST","result/add/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"}

HTTP Request

POST https://api.skopenow.com/v1/result/add/{id}

Content type: application/json

URL Parameters

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

Request Body

When an API request is made you will need to set the following parameters:

Parameter Type Description
identifiers array ex.[‘Rob Douglas + NY, US’]
rank integer ex. 1
assoc boolean ex. [true, false] true if you want to add this to association person and false to add be added to main person ,
source string ex. facebook
title string ex. Facebook Profile
url string ex. https://www.facebook.com/rob.douglas.7923

The code request should return something like this:

Remove Results

Use our API to remove content from the PDF reports. “`php <?php try { // Remove request $request = [ "remove” => [ “results_ids” => [“y6QKDtuRqfLeCXP2-fOM0NuTH_”,“y6QKDtuRqfLeCXP2”], ] ]; $response = $skopenow->post(“result/remove/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 '{
  "remove" : {
    "results_ids":["y6QKDtuRqfLeCXP2-fOM0NuTH_","y6QKDtuRqfLeCXP2"],
  }
}' "https://api.skopenow.com/v1/result/add/abCD-E12_3"
var request = {
 "remove" : {
    "results_ids":["y6QKDtuRqfLeCXP2-fOM0NuTH_","y6QKDtuRqfLeCXP2"],
  }
};

skopenow.json("POST","result/remove/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"}

HTTP Request

POST https://api.skopenow.com/v1/result/remove/{id}

Content type: application/json

URL Parameters

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

Request Body

When an API request is made you will need to set the following parameters:

Parameter Type Description
ids array ex. ["aftrjkjdHHJJ545,"kjhjkh456f”,..]

The code request should return something like this:

Person API

Name and Location

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

{
 "inputs": {
  ...
 },
 "filters": {
  ...
 },
 "output": {
  ...
 }
}

The following are examples:

<?php
try {

  $request = [
    "inputs" => [
      "name" => ["Robert James"],
      "location" => ["Oyster Bay, NY"]
    ],
    "output" => [
      "type" => "json",
      "destination" => "url",
      "logo_url" => "https://www.skopenow.com/images/new_logo.png",
      "company_name" => "Skopenow",
      "url" => "http://api.webhookinbox.com/i/123456/in/"
    ]
  ];
  $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",
     "logo_url" : "https://www.skopenow.com/images/new_logo.png",
     "company_name" : "Skopenow",
     "url": "http://api.webhookinbox.com/i/123456/in/"
  }
}' "https://api.skopenow.com/v1/search"
var request = {
  "inputs": {
    "name": ["Robert James"],
    "location": ["Oyster Bay, NY"]
  },
  "output": {
    "type": "json",
    "destination": "url",
    "logo_url" : "https://www.skopenow.com/images/new_logo.png",
    "company_name" : "Skopenow",
    "url": "http://api.webhookinbox.com/i/123456/in/"
  }
};

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"}

The above code can also return a response from the Reverse API if an exact match is not found. Please refer to the Reverse API section for the sample response.

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.

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 request for the Business API’s required inputs looks like the this.

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

In order for the Business 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. [“Robert Douglas”,“Robert James”]
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 optional inputs for the Business API look like the following:

{
  "name": ["..."],
  "location": ["..."],
  "address": ["..."],
  "phone": ["..."],
  "email": ["..."],
  "username": ["..."],
  "birthdate": ["..."],
  "age": ["..."],
  "occupation": ["..."],
  "school": ["..."],
  "keyword": ["..."],
  "behaviors": ["..."],
  "associate_name":["..."],
  "associate_location":["..."],
  "search_specificity":["..."],
  "incident_date": ["..."],
  "interest_from": ["..."],
  "interest_to": ["..."],
  "flag": ["..."],
  "incident": "XXXXX",
  "claim": "XXXXX",
  "suggestion_key":"...",
}
Parameter Type Description
name array ex. [“Rob Douglas”]
location array ex. [“Oyster Bay, NY”]
address array ex. [“1 Maple St Brooklyn, NY 11225”]
phone array ex. [“(516) 330-5677”]
email array ex. [“Robert@skopenow.com” ,“Marc@skopenow.com”]
birthdate array ex. [“mm/dd/yyyy” ,“mm/dd/yyyy”]
age array ex. [“18” ,“23”] or [“38-40”, “33-35”]
occupation array ex. [“Software Developer” ,“CEO”,“Photographer”]
school array ex. [“Vanderbilt University”, “Oyster Bay High School”]
username array ex. [“RobDouglas2016”] - Social media usernames
keyword array ex. [“skopenow”, “sport”]
behaviors array ex. [“Physical Activity”, “Adult Content”, “ NSFW”, “Mysogeny”, “Radical Behavior”, “Crime”, “Drug Paraphernalia”, “ Alchohol”, “Smoking”, “Vehicle Usage”, “Contraband”, “Expletive Language”, “Flaunting”, “Referenced Item”]
incident_date array ex. [“mm/dd/yyyy” ,“mm/dd/yyyy”]
interest_from array ex. [“mm/dd/yyyy” ,“mm/dd/yyyy”]
interest_to array ex. [“mm/dd/yyyy” ,“mm/dd/yyyy”]
flag string ex. “xxx”
incident string ex. “accident”
claim string ex. “12145d”
suggestion_key string ex. “abscd12345ww”

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, domain, and usernames. If you need further refinement, attributes such as associate_name, associate_location, and formed can be used to further narrow your results. Passing email, keyword, behavior, phone, address, or fein will change your general search to a reverse search, which does not effect the number of API calls made.

Filters

The filters for the Person API look like this:

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

Example Person API Post json body with inputs and output settings set

{
    "inputs": {
        "name": ["Robert James"],
        "location": ["Oyster Bay, NY"],
        "school": ["NYU"]
    },
    "filters": {
        "name": "exact",
      "location": "0",
        "exact": true
    }
}

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; however, 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 [“all”, “exct-sm”, “exct-bg”, “state”]. 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 output settings for the Person API look like this:

{
 "type" : "pdf",
 "destination" : "ftp",
 "logo_url" : "https://www.skopenow.com/images/new_logo.png",
  "company_name" : "Skopenow",
 "ftp": {
    "host": "ftp.example.com",
    "port": 21,
    "username": "ftpuser",
    "password": "ftppassword"
 }
}

Example Person API Post JSON body with inputs and output settings set.

{
    "inputs": {
        "name": ["Robert James"],
        "location": ["Oyster Bay, NY"],
        "school": ["NYU"]
    },
    "outputs": {
        "type" : "pdf",
        "destination" : "ftp",
        "logo_url" : "https://www.skopenow.com/images/new_logo.png",
        "company_name" : "Skopenow",
        "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
logo_url string your company logo,
company_name string your company name,
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/{id}

URL Parameters

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

Regenerating 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 {
  //Search
  $request = [
    "output" => [
      "type" => "json",
      "destination" => "url",
      "logo_url" => "https://www.skopenow.com/images/new_logo.png",
      "company_name" => "Skopenow",
      "url" => "http://api.webhookinbox.com/i/123456/in/"
    ]
  ];
  $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://api.webhookinbox.com/i/123456/in/",
     "logo_url" : "https://www.skopenow.com/images/new_logo.png",
     "company_name" : "Skopenow",
  }
}' "https://api.skopenow.com/v1/search/abCD-E12_3"
var request = {
  "output": {
    "type": "json",
    "destination": "url",
    "url": "http://api.webhookinbox.com/i/123456/in/",
    "logo_url" : "https://www.skopenow.com/images/new_logo.png",
    "company_name" : "Skopenow",
  }
};

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/{id}

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.

Extract Data

This is a new feature that allows you to request additional information from a specific source. You can request additional parameters using date and content type.

<?php
try {
  // extract request
  $request = [
    "extract_data" => [
    "date_before" => "11/22/2017",
    "date_after" => "11/14/2018",
    "extract_types" => ["photos_by","photos_interacted"],
    "source" => "facebook",
    "url" => "https://www.facebook.com/rob.douglas.7923",
    "result_id" => "y6QKDtuRqfLeCXP2-fOM0NuTH_",
    ],
  ];
  $response = $skopenow->post("result/extract/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 '{
  extract_data" : {
    "date_before": "11/22/2017",
    "date_after": "11/14/2018",
    "extract_types": ["photos_by","photos_interacted"],
    "source": "facebook",
    "url": "https://www.facebook.com/rob.douglas.7923",
    "result_id": "y6QKDtuRqfLeCXP2-fOM0NuTH_",
  }
}' "https://api.skopenow.com/v1/result/extract/abCD-E12_3"
var request = {
  "extract_data" : {
    "date_before": "11/22/2017",
    "date_after": "11/14/2018",
    "extract_types": ["photos_by","photos_interacted"],
    "source": "facebook",
    "url": "https://www.facebook.com/rob.douglas.7923",
    "result_id": "y6QKDtuRqfLeCXP2-fOM0NuTH_",
  }
};

skopenow.json("POST","result/extract/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"}

HTTP Request

POST https://api.skopenow.com/v1/result/extract/{id}

Content type: application/json

URL Parameters

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

Request Body

When an API request is made you will need to set the following parameters: source must be in on of these values: facebookortwitter orinstagram orYoutube orlinkedin

Parameter Type Description
date_before date ex. “11/22/2017”
date_after date ex. “11/14/2018”
extract_types array ex. [“photos_by”,“photos_interacted”,…] the following table show each source and its data type
url string ex. “https://www.facebook.com/rob.douglas.7923”
result_id string ex. “y6QKDtuRqfLeCXP2-fOM0NuTH_”

Source and types

Each Source has it own types each type may be Pages, or Content. The following tables show each source and its types

Facebook

Type name Content Require Date Description
all content false All Content (Delayed Process)
photos_tagged_in content true Photos Tagged In
photos_by content true Photos By
photos_interacted content true Photos Interacted
photos_commented content true Photos Commented
photos_liked content true Photos Liked
photos_in_groups content true Photos in Groups
posts_in_events content true Posts in Events
posts_made content true Posts Made
posts_tagged content true Posts Tagged
posts_liked content true Posts Liked
posts_commented content true Posts Commented
places content false Places
events content false Events
groups content false Groups
check_ins content false Check Ins
videos_uploaded content true Videos Uploaded
videos_tagged content true Videos Tagged
videos_liked content true Videos Liked
videos_interacted content true Videos Interacted
videos_commented content true Videos Commented
friends content false Friends
pages content false Pages
page_about page false About
page_photos page false Photos
page_groups page false Groups
page_music page false Music
page_reviews page false Reviews
page_events page false Events
page_videos page false Videos
page_check_ins page false Check Ins
page_sports page false Sports
page_likes page false Likes

Twitter

Type name Content Require Date Description
all content false All (delayed process)
tweets content true Tweets
tweeted content true Tweeted
media content true media
photos_by_subject content true Photos by Subject
photos_of_subject content true Photos of Subject
videos_by_subject content true Videos by Subject
videos_of_subject content true Videos of Subject
news content false News
hashtags content false Hashtags
tw_followers page true Followers
tw_following page true Following
likes page true Likes

Instagram

Type name Content Require Date Description
all content false All Content
photos content false Subject’s photos
insta_videos content false Subject’s Videos
insta_tags content false Tags

Youtube

Type name Content Require Date Description
all both false All Content (delayed process)
youtube_video contents true Subject’s Videos
playlist pages false Playlist
channels pages false Channels
discussion pages false Discussion
about pages false About

Linkedin

Type name Content Require Date Description
all content false All Content
endorsers content false Subject’s Endorsers
co content false Subject’s Co-workers
posts content true Subject’s posts
articles content false Articles by Subject
activity content false Subject’s Activity
influencers content false Subject’s Influencers
companies pages false Companies
group pages false Group

ScreenShoot Recapture

<?php
try {
  // Recapture request
  $request = [
    "recapture_data" => [
      "result_id" => "y6QKDtuRqfLeCXP2-fOM0NuTH_",
    ],
  ];
  $response = $skopenow->post("result/screenshot/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 '{
  "recapture_data" : {
    "result_id":"y6QKDtuRqfLeCXP2-fOM0NuTH_",
  }
}' "https://api.skopenow.com/v1/result/screenshot/abCD-E12_3"
var request = {
  "recapture_data" : {
    "result_id":"y6QKDtuRqfLeCXP2-fOM0NuTH_",
  }
};

skopenow.json("POST","result/extract/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"}

HTTP Request

POST https://api.skopenow.com/v1/result/screenshot/{id}

Content type: application/json

URL Parameters

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

When an API request is made you will need to set the following parameters:

Parameter Type Description
result_id string ex. “y6QKDtuRqfLeCXP2-fOM0NuTH_”

Add Source as a Result

<?php
try {
  // Source request
  $request = [
    "source_data" => [
    "identifiers" => ["Rob Douglas"],
    "assoc" => false,
    "rank" => "1",
    "source" => "facebook",
    "title" => "Rob Douglas",
    "url" => "https://www.facebook.com/rob.douglas.7923",
    ]
  ];
  $response = $skopenow->post("result/add/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 '{
  "source_data" : {
    "identifiers":["Rob Douglas"],
    "rank":"1",
    "assoc" => false,
    "source":"facebook",
    "title":"Rob Douglas",
    "url":"https://www.facebook.com/rob.douglas.7923",
}
}' "https://api.skopenow.com/v1/result/add/abCD-E12_3"
var request = {
  "source_data" : {
    "identifiers":["Rob Douglas"],
    "rank":"1",
    "assoc" => false,
    "source":"facebook",
    "title":"Rob Douglas",
    "url":"https://www.facebook.com/rob.douglas.7923",
  }
};

skopenow.json("POST","result/add/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"}

HTTP Request

POST https://api.skopenow.com/v1/result/add/{id}

Content type: application/json

URL Parameters

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

Request Body

When an API request is made you will need to set the following parameters:

Parameter Type Description
identifiers array ex.['Rob Douglas + Ny, US’]
rank integer ex. 1
assoc boolean ex. [true, false] true if you want to add this to association person and false to add be added to main person ,
source string ex. facebook
title string ex.facebook result
url string ex.https://www.facebook.com/rob.douglas.7923

The code request should return something like this:

Removing Results

<?php
try {
  // Remove request
  $request = [
    "remove" => [
    "results_ids" => ["y6QKDtuRqfLeCXP2-fOM0NuTH_","y6QKDtuRqfLeCXP2"],
    ]
  ];
  $response = $skopenow->post("result/remove/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 '{
  "remove" : {
    "results_ids":["y6QKDtuRqfLeCXP2-fOM0NuTH_","y6QKDtuRqfLeCXP2"],
  }
}' "https://api.skopenow.com/v1/result/add/abCD-E12_3"
var request = {
 "remove" : {
    "results_ids":["y6QKDtuRqfLeCXP2-fOM0NuTH_","y6QKDtuRqfLeCXP2"],
  }
};

skopenow.json("POST","result/remove/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"}

HTTP Request

POST https://api.skopenow.com/v1/result/remove/{id}

Content type: application/json

URL Parameters

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

Request Body

When an API request is made you will need to set the following parameters:

Parameter Type Description
ids array ex. [“aftrjkjdHHJJ545,"kjhjkh456f”,..]

The code request should return something like this:

Reverse API

The API response for a reverse lookup.

<?php
try {
  // Test Reverse Search
  $request = [
    "inputs" => [
      "phone" => ["5163305677"],
    ],
    "output" => [
      "type" => "pdf",
      "destination" => "url",
      "url" => "http://api.webhookinbox.com/i/123456/in/",
      "logo_url" => "https://www.skopenow.com/images/new_logo.png",
      "company_name" => "Skopenow",
    ]
  ];
  $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://api.webhookinbox.com/i/123456/in/",
     "logo_url" : "https://www.skopenow.com/images/new_logo.png",
     "company_name" : "Skopenow",
  }
}' "https://api.skopenow.com/v1/search"
// Test Reverse Search
var request = {
  "inputs": {
    "phone": ["12345678910"],
  },
  "output": {
    "type": "pdf",
    "destination": "url",
    "url": "http://api.webhookinbox.com/i/123456/in/",
    "logo_url" : "https://www.skopenow.com/images/new_logo.png",
    "company_name" : "Skopenow",
  }
};

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 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 an address 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 a 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 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 a filter settings looks like the this.

{
  "name": "exact",
  "location": "exact",
  "family/owners": 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 [“all”, “exct-sm”, “exct-bg”, “state”]. 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": ["..."],
  "birthdate": ["..."],
  "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”]
birthdate array ex. [“mm/dd/yyyy” ,“mm/dd/yyyy”]
age array ex. [“18” ,“23”] or [“38-40”, “33-35”]
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_key should 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 sure option 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_key represents 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 that 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": {
  ...
 }
}

Association API

The association API can be used to find connections between multiple parties. We have a business to person and person to person search. The attributes passed along through the Association API are the same as the Person and Business API.

The API response for a Business or Person Association Search.

<?php
try {
  $request = [
    "inputs" => [
      "associations" => [
        "name": ["..."],
        "location": ["..."],
        "address": ["..."],
        "phone": ["..."],
        "email": ["..."],
        "birthdate": ["..."],
        "age": ["..."],
        "occupation": ["..."],
        "school": ["..."],
        "keyword": ["..."],
        "behaviors": ["..."],
        "incident_date": ["..."],
        "interest_from": ["..."],
        "interest_to": ["..."],
        "flag": ["..."],
        "incident": "XXXXX",
        "claim": "XXXXX",
        "username": "XXXXX",


      ],
    ],
    "output" => [
      "type" => "pdf",
      "destination" => "url",
      "url" => "http://api.webhookinbox.com/i/123456/in/",
      "logo_url" => "https://www.skopenow.com/images/new_logo.png",
      "company_name" => "Skopenow",
    ]
  ];
  $response = $skopenow->post("person", ['json' => $request]);
  $response = $skopenow->post("business", ['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" : {
    "associations": {
      "name" : ["Rob Douglas"],
      "location" : ["Oyster Bay, NY"],
      "phone" : ["12345678910"],
   }
  },
  "output" : {
     "type" : "pdf",
     "destination" : "url",
     "url": "http://api.webhookinbox.com/i/123456/in/",
     "logo_url" : "https://www.skopenow.com/images/new_logo.png",
     "company_name" : "Skopenow",
  }
}' "https://api.skopenow.com/v1/search"
// Test Business or Person Association Search
var request = {
  "inputs" : {
    "associations": {
      "name" : ["Rob Douglas"],
      "location" : ["Oyster Bay, NY"],
      "phone" : ["12345678910"],
   }
  },
  "output": {
    "type": "pdf",
    "destination": "url",
    "url": "http://api.webhookinbox.com/i/123456/in/",
    "logo_url" : "https://www.skopenow.com/images/new_logo.png",
     "company_name" : "Skopenow",
  }
};

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

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

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

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

Association searches will include all of the same data shown in a Person or Business report but it will also show any links found between the parties.

Manually Add Association Content

You can manually add content to your association’s digital record.

<?php
try {
  // Source request
  $request = [
    "source_data" => [
    "identifiers" => ["Rob Douglas"],
    "rank" => "1",
    "assoc" => true
    "source" => "facebook",
    "title" => "Rob Douglas",
    "url" => "https://www.facebook.com/rob.douglas.7923",
    ]
  ];
  $response = $skopenow->post("result/add/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 '{
  "source_data" : {
    "identifiers":["Rob Douglas"],
    "rank":"1",
    "assoc": true
    "source":"facebook",
    "title":"Rob Douglas",
    "url":"https://www.facebook.com/rob.douglas.7923",
}
}' "https://api.skopenow.com/v1/result/add/abCD-E12_3"
var request = {
  "source_data" : {
    "identifiers":["Rob Douglas"],
    "rank":"1",
    "assoc": true
    "source":"facebook",
    "title":"Rob Douglas",
    "url":"https://www.facebook.com/rob.douglas.7923",
  }
};

skopenow.json("POST","result/add/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"}

HTTP Request

POST https://api.skopenow.com/v1/result/add/{id}/

Content type: application/json

URL Parameters

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

Request Body

When an API request is made you will need to set the assoc parameter to true if you want to run an Association search. Otherwise the default will be false.

The follow parameters can be used to add manual results to your Association search:

Parameter Type Description
identifiers array ex.['Rob Douglas + Ny, US’]
rank integer ex. 1
source string ex. facebook
title string ex. facebook result
url string ex. https://www.facebook.com/rob.douglas.7923
assoc boolean ex. true

The code request should return something like this:

Attributes

You can use the same attributes listed within the Person and Business API section to include in our query.

Return

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

{
  "code": 200,
  "suggestions": {
    main_suggestions: {}
    associations_suggestions: {
      "source": "tloxp",
      "search_type": "person",
      "first_name": "Lauren",
      "middle_name": null,
      "last_name": "Douglas",
      "full_name": "Lauren Douglas",
      "location": "Shawnee, OK, USA",
      "street": "1130 E Independence St Apt 204",
      "address": "1130 E Independence St Apt 204, Shawnee, OK, USA",
      "city": "Shawnee",
      "state": "OK",
      "zip": "74804",
      "country": "US",
      "relatives" : "",
      "addresses": [
        {
          "address": "1 Maple St, Oyster Bay, NY",
          "city": "Oyster Bay, NY",
          "state": "NY",
          "zip": "11771"
        },
        ...
      ],
      "emails": [
      {
        "value": "rdouglas2@yahoo.com",
        "sources": [
              "skopenow"
          ],
        "persons": [
              "HPRG"
              ]
      }
        ...
              ],
      "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"
    "associations" : {
      "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 a 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 for a search that receives a score of less than a 0.5.

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

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