Introduction
SpyCloud's IDLink API is a programmatic interface into our vast collection of breach records and surrounding metadata.
See API Guidelines for authentication, configuration, and error handling details. Most API resources support pagination. See Pagination.
API Reference
How It Works
IDLink pivots on the following assets within breach records to find the full picture of a user's online identity.
| Pivotable Assets |
|---|
| backup_email |
| social_handles |
| password |
| bank_number |
| driver_license |
| national_id |
| passport_number |
| social_security_number |
| infected_machine_id |
| log_id |
IDLink applies weights from 0 - 1,000 to the following assets to build cumulative confidence in the relationships.
| Assets used in Confidence Calculations |
|---|
| backup_email |
| email_username |
| username |
| social_* |
| full_name |
| first_name |
| last_name |
| dob |
| phone |
| password |
| ssn |
| address_* |
| city |
| infected_machine_id |
| log_id |
| bank_number |
| passport_number |
| national_id |
| ip_addresses |
Response Format
IDLink can provide a the response as a list of JSON records, similar to our other APIs, or in the JSON Graph Format.
The JSON Graph Format is focused on capturing basic graph structure in a convenient to use format. It allows for the use of metadata objects in the graph, nodes and edges which can be used for any other graph data that needs to be managed in your graph data files (e.g. graph layout, styling, algorithm results, etc).
The format first shows breach records (or "nodes"), followed by the relationships ("rels") between the nodes. The nodes are connected via "document_id" ("start" and "end") and will also show which fields matched between them.
In this example response below, we can see that the level 1 and level 2 record are matched on backup_email:
{
"graph": {
"nodes": [
{
"label": "ROOT: email",
"level": 0,
"props": {
"document_id": "ROOT"
}
},
{
"label": "email: [[email protected]](mailto:[email protected])",
"level": 1,
"props": {
"domain": "gmail.com",
"password": "e4c4a52b480e358794d0855df824e2c8ef8761bc",
"severity": 20,
"backup_email": "[[email protected]](mailto:[email protected])",
"email_username": "bob.smith",
"spycloud_publish_date": "2016-10-21T00:00:00Z",
"email_domain": "gmail.com",
"source_id": 33,
"password_type": "sha1",
"email": "[[email protected]](mailto:[email protected])",
"document_id": "d4a52819-67d3-795f-8f8f-c736097h8008",
"password_plaintext": "password1",
"record_modification_date": "2020-10-25T00:00:00Z"
}
},
{
"label": "social_handle: bob-smith-55",
"level": 2,
"props": {
"country": "UNITED STATES",
"dob": "1965-04-16T00:00:00Z",
"full_name": "Bob Smith",
"social_linkedin": [
"bob-smith-55"
],
"email": "[[email protected]](mailto:[email protected])",
"source_id": 38107,
"backup_email": "[[email protected]](mailto:[email protected])",
"document_id": "2hn95n5c-979d-4663-931d-fb6da5333a03",
"spycloud_publish_date": "2021-10-21T00:00:00Z",
"email_domain": "hotmail.com",
"email_username": "bsmith",
"domain": "hotmail.com",
"country_code": "US",
"severity": 5
}
}
],
"rels": [
{
"start": "d4a52819-67d3-795f-8f8f-c736097h8008",
"end": "2hn95n5c-979d-4663-931d-fb6da5333a03",
"type": "MATCH: backup_email",
"metadata": {
"confidence": 1000,
"type": "variable_weighting"
}
}
]
},
"nodeCount": 2,
"relationshipCount": 2
}