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.

API Reference

How It Works

IDLink starts with an identity attribute and returns matching breach records. It then auto-pivots on supported attributes within those records to discover additional related records and build a more holistic view of an identity.

Most searchable attributes can also be used to expand the graph. IP addresses can be used as a query input, but are not used as pivot points during graph traversal.

Asset	Query Input	Used for Graph Pivots
email	Yes	Yes
backup_email	Via email	Yes
phone	Yes	Yes
username	Yes	Yes
social_handle	Yes	Yes
password	Yes	Yes
bank_number	Yes	Yes
driver_license	Yes	Yes
national_id	Yes	Yes
passport_number	Yes	Yes
social_security_number	Yes	Yes
infected_machine_id	Yes	Yes
log_id	Yes	Yes
ip_address	Yes	No

Confidence

IDLink assigns weights from 0 to 1,000 to identity attributes when calculating cumulative confidence in relationships between records.

Assets Used in Confidence Calculations
email
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 supports two response formats using the output_format query parameter:

Value	Description
`json`	Returns breach records as JSON records, similar to other SpyCloud APIs.
`json-graph-spec`	Returns records and their relationships as graph data.

JSON Graph Format

The JSON Graph format represents the structure of an IDLink query using nodes and relationships.

The graph.nodes array contains the root search asset and breach records discovered during the query. Each node includes a level showing where it was found in the traversal:

level: 0 represents the root search.
level: 1 represents records directly associated with the searched asset.
Higher levels represent records discovered through additional pivots.

The graph.rels array describes relationships between nodes. The start and end values reference node identifiers, while type identifies the attribute that connected the records.

Relationship metadata can also include the confidence associated with that connection.

In the abridged example below, a level 1 record and a level 2 record are connected by the same backup_email value:

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