×

Login to Safe Shepherd

Recover your password

Safe Shepherd API Documentation

Getting Started

The Safe Shepherd API allows you to easily build internet monitoring and cleanup services into your product. Below, we'll cover the steps to get up and running quickly.

Creating your first User

For each customer account, you will create a user through the API, which will track their personal information and all associated links and records found by Safe Shepherd. You'll consistently reference users; they are the foundation of interacting with the API.

The Create user endpoint requires your API credentials (as with all endpoints from here on), and a basic amount of personal information to identify the user. Providing additional information, such as their birth date, will produce more accurate results when we scan the Internet for records.

Steps to success

To create a user, you'll need at a minimum their first name, last name, city and state.

Try in Playground
  POST /api/:integration_name/:api_key/v2/users(.:format)

  api_key=<your API key>
  api_secret=<your API secret>
  first_name=Jon
  last_name=Snow
  addresses=[{city:'Winterfell',state'WS',country:'USA'}]

When you create a user, we'll immediately begin scanning for links and removable records with the user's personal information.

The API will return a <user struct>, encoded in either JSON or XML. It is important to store the id and secret from this result, which is necessary for future user authentication.

"user": {
  "id": 162,
  "secret": "6ea97ec680144c5c5c98892eb51b5e640c4d143a",
  ...,
  "records": [
    {
      "id": 5697,
      "name": "Jon Snow",
      "age": 23,
      "site": "My Life",
      "relations": [
        "Ned Stark"
      ],
      "locations": [
        "Winterfell, WS",
        "The Wall, WS"
      ]
      ...
    },
    ...
  ],
  "links": [
    {
      "url": "http://awoiaf.westeros.org/index.php/Jon_Snow",
      "title": "Jon Snow - A Wiki of Ice and Fire"
    },
    ...
    }
  ]
}

Get Alerts for User

Once a user is created, we'll immediately begin processing record removals. As removals are processed, we'll generate alerts which you can send to your users. Alerts may additionally include a `guide` with further information on the site the alert pertains to and how to manually remove your PII from the website. These alerts can be embedded in communications with your users, such as e-mails or push notifications.

The Get user alerts endpoint pulls all alerts for a given user account.

Steps to success

All you need to pull alerts is the user authentication from the previous step.

Try in Playground
GET /api/:integration_name/:api_key/v2/users/:user_id/alerts/:id(.:format)

api_key=<your API key>
api_secret=<your API secret>
user_id=<user id returned during user creation>
secret=<user secret returned during user creation>

You'll get back a list of alerts for the user.

"alerts": [
  {
    "text": "Safe Shepherd API has submitted an Automated opt-out to Intelius to remove a record which we've identified as having your information.",
    "html": "Safe Shepherd API has submitted an Automated opt-out to Intelius to remove a record which we've identified as having Tommy Lee Jones.",
    "guide": "Intelius is an online database of personal information that aggregates nearly everything about you, including your home addresses, phone numbers, age, date of birth, relatives, income, aliases, and court records, past and present. ...",
    "opt_out_procedure": ["Visit Intelius' [Opt Out page](https://www.intelius.com/optout.php).", ... ],
    "source_type": "record",
    "source": { "record": { id: 318, name: "Tommy Lee Jones", site: "Intelius", status: "discovered", ... } }
  }
]

Completing a User Profile

Certain people search websites may require additional information about a user (such as an email or street address) in order to correctly identify the record to be removed (and that the request is coming from the end-user). If this is the case, you may be required to update the user with additional information. After updating the required fields, we will automatically submit removals from these people search websites.

Steps to success

Get all user records will show any missing information required to remove a user's records.

Try in Playground
PUT /api/:integration_name/:api_key/v2/users/:id(.:format)

api_key=<your API key>
secret=<your API secret>
addresses=[{address1:'1 Kings Lane',city:'Winterfell',state'WS',country:'USA'}]