# Retrieving Identity Exposures

The following API endpoint allows you to retrieve historical exposures for a given identity, using your API key.  This can be used in complementary fashion with the monitoring APIs to both monitor for new exposures of a given identity, after pulling the past exposures.  Note that you will need to have Identity Breach Monitoring added to your subscription before you can call this API.

***

## Pull historical exposures for a specific identity

> Allows you to pull historical exposure details for an individual identity.  The identity can include elements such as name, physical address, phone numbers, government IDs, email addresses, credit cards, etc.

```json
{"openapi":"3.0.0","info":{"title":"Enzoic API","version":"1.3.0"},"tags":[{"name":"identityMonitoring","description":"APIs which are used to set targets for identity monitoring"}],"servers":[{"url":"https://api.enzoic.com/v1"}],"security":[{"enzoic_auth":[]}],"components":{"securitySchemes":{"enzoic_auth":{"type":"http","scheme":"basic","bearerFormat":"Base64(your_api_key:your_api_secret)","description":"The Enzoic API uses a basic auth scheme where the username is your API key and the password is your API secret.  \nSee https://docs.enzoic.com/enzoic-api-developer-documentation/using-the-enzoic-api#api-authentication for more details.       \n"}},"schemas":{"IdentityExposuresPostBody":{"type":"object","description":"The identity to pull exposures for.  One of the following sets of fields is required and must be provided or \nthe request will be rejected with a 400:\n- firstName, lastName, country, and governmentID\n- emails\n- creditCards\n- cryptocurrencyWallets\n- urls\n- ip4Addresses\n- ip6Addresses\n","required":["firstName","lastName","country"],"properties":{"firstName":{"type":"string","description":"Legal first name"},"lastName":{"type":"string","description":"Legal last name"},"country":{"type":"string","description":"The ISO 3166-1 alpha 2 country code for the individual"},"address1":{"type":"string","description":"Physical street address"},"address2":{"type":"string","description":"Physical address line 2"},"city":{"type":"string","description":"Physical address city"},"province":{"type":"string","description":"Physical address province/state (2 letter abbreviation for US states)"},"postalCode":{"type":"string","description":"Physical address postal code (5-digit ZIP code in US)"},"governmentID":{"type":"object","description":"A national identifier for this individual (e.g. Social Security Number in the US)","required":["country","value"],"properties":{"country":{"type":"string","description":"The ISO 3166-1 alpha 2 country code for the government ID"},"value":{"type":"string","description":"The value of the government ID"}}},"emails":{"type":"array","description":"An array of email addresses associated with this identity","items":{"type":"string"}},"phoneNumbers":{"type":"array","description":"An array of phone numbers associated with this identity","items":{"type":"object","required":["value"],"properties":{"country":{"type":"string","description":"The ISO 3166-1 alpha 2 country code for the phone number (optional the phone number is in E164 format)"},"value":{"type":"string","description":"The phone number, preferably in E164 format (e.g. +12123233232)"}}}},"creditCards":{"type":"array","description":"An array of payment card numbers associated with this identity","items":{"type":"string"}},"cryptocurrencyWallets":{"type":"array","description":"An array of cryptocurrency wallet addresses","items":{"type":"string"}},"urls":{"type":"array","description":"An array of URLs associated with this identity.  The URL scheme must be included and can be http, https, ftp, ftps, smtp or smtps.  URLs are partial match from the beginning of the value, so if https://www.enzoic.com/some/page was found in a breach and https://www.enzoic.com was the URL being monitored, this would be considered a match.\n","items":{"type":"string"}},"ip4Addresses":{"type":"array","description":"An array of IPv4 addresses to monitor","items":{"type":"string"}},"ip6Addresses":{"type":"array","description":"An array of IPv6 addresses to monitor","items":{"type":"string"}},"secondaryMatchItems":{"type":"array","description":"An array of secondary items to match.  Secondary matches occur after an identity is matched using the core PII provided above (name, government ID, etc.).  If an identity is matched using the core PII, Enzoic looks within close proximity to it for secondary matches that should be flagged as well.  Secondary match information can include anything relatively unique to the user and not already covered in one of the core PII categories, e.g. financial account numbers, localty card numbers, a US Employer Identification Number (EIN), passport number, etc.","items":{"type":"object","required":["description","value"],"properties":{"description":{"type":"string"},"value":{"type":"string"}}}}}},"IdentityExposuresPostResponse":{"type":"object","properties":{"matches":{"description":"An array of past exposures found for the provided identity","type":"array","items":{"type":"object","properties":{"containsSingleIdentity":{"type":"boolean","description":"This exposure contained data for only a single identity.  All of the rawMatchSource is relevant to only this identity."},"exposureID":{"type":"string","description":"The ID of the Exposure. Use the /exposure-details call to retrieve details for this exposure."},"matchedItems":{"type":"object","description":"An object containing just the queried values which were matched in this breach.  Each value will consist of a JSON object with queriedValue and foundValue fields, since the formatting of the value found may be different than what was passed in.","properties":{"foundValue":{"type":"string","description":"The value found in the breach"},"queriedValue":{"type":"string","description":"The value being monitored"}}},"rawMatchSource":{"type":"string","description":"A snippet of text from the breach source showing the content around where the matches were found."}}}}}}}},"paths":{"/identity-exposures":{"post":{"tags":["identityMonitoring"],"summary":"Pull historical exposures for a specific identity","operationId":"getIdentityExposures","description":"Allows you to pull historical exposure details for an individual identity.  The identity can include elements such as name, physical address, phone numbers, government IDs, email addresses, credit cards, etc.","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentityExposuresPostBody"}}}},"responses":{"200":{"description":"The response body contains the requested results.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IdentityExposuresPostResponse"}}}}}}}}}
```