| Name | Type | Description |
|---|---|---|
| Auth-Token | string | Input your unique token here. This is required to submit an API request. |
| Reference-Id (Optional) |
string | Identifier that will be returned to the response to help you track the request. |
| Timeout-Seconds (Optional) |
integer | Maximum time you are prepared to wait for a response, expressed in seconds. Acceptable values: 2-15. If a timeout occurs, an HTTP status code of 408 - Request Timeout will be returned. The default value of this setting is 15. |
| Add-Metadata (Optional) |
boolean | Specify whether the response should return all fields and values, in addition to the main core information. The default value of this setting is true. |
In the request body you can specify:
| Name | Type | Description | |
|---|---|---|---|
| components | object | Object defining the input components. | |
| first_name | collection | Collection containing the first name of the individual. | |
| middle_name | collection | Collection containing the middle name of the individual. | |
| last_name | collection | Collection containing the last name of the individual. | |
| address_line_1 | collection | Collection containing the address of the individual. | |
| town | collection | Collection containing the town, city or suburb. | |
| region | collection | Collection containing the state or province. | |
| postal_code | collection | Collection containing the post/zip code. | |
| collection | Collection containing the email of the individual. | ||
| phone | collection | Collection containing the phone number of the individual. | |
| country_iso_2 | collection | Collection containing the ISO 2 code of the country of the individual. | |
| IP_address | collection | Collection containing the IP address of the individual. | |
| user_agent | collection | Collection containing the user agent of the individual. | attributes | collection | Collection containing the type of the request. |
Response times
| Name | Type | Description |
|---|---|---|
| Reference-Id (Optional) |
string | Identifier that was supplied by you in the request header to help you track the request. |
The response from the API returns the below fields within a result object. Should an error occur, an error object is returned instead.
| Name | Type | Description |
|---|---|---|
| score | integer | The risk score for the email address provided, low score: 0, High score: 100. |
| tumbling_risk | integer | A score indicating multiple variations of the same email address. 0 indicates no tumbling detected, while values of 1, 2 and 3 indicated a linear risk of tumbling detected. |
| domain_risk | integer | A score indicating the domain risk level, based on historical information and industry data. Low score: 0, High score: 10. |
| Name | Type | Description |
|---|---|---|
| date_first_seen | string | The date the email address first appeared in the records. |
| longevity | integer | A score relating to when the email address was first discovered. From 0 (not discovered) to 3 (Discovered over a year ago). |
| velocity | integer | A score reflecting the activity of the email address over the last 6 months, from 0 (no activity) to 10 (most active). |
| popularity | integer | A score assessing the email address's visibility over the last 12 months based on the number of sources that have received the address, ranging from 0 (no sources) to 10 (most sources). |
| domain | string | Collection containing the email domain info, including date_first_seen, longevity, velocity, popularity and domain_type. |
| confidence | string | Collection containing the confidence of the email. |
| verbose_output | string | The verbose output of the validation. |
| verbose_reason | string | The verbose output description of the validation. |
If the HTTP status code of the response is 200, among other fields, the response body will contain a confidence level and verbose details.
| Confidence | Verbose | Description |
|---|---|---|
| verified | verified | The mailbox exists, is reachable, and is not known to be illegitimate or disposable. |
| undeliverable | mailboxDisabled | The mailbox is disabled. |
| mailboxDoesNotExist | The mailbox does not exist. | |
| mailboxFull | The mailbox is full. | |
| syntaxFailure | The syntax of the specified email address is incorrect. | |
| internationalCharactersUnsupported | The domain does not support the use of international characters (e.g. á, é or ø). | |
| unreachable | unreachable | The domain is not responding to validation requests or does not have any active mail servers. |
| illegitimate | illegitimate | Seed, spamtrap, black hole, technical role account or inactive domain. |
| roleAccount | Role accounts such as support, sales, info etc. | |
| typoDomain | The domain of the email address you've provided was close to a common domain and, although it exists, it is highly unlikely to be correct. | |
| localPartSpamTrap | Known local portions of the email address that may indicate spam traps. | |
| Profanity | The email address contains profanity. | |
| disposable | disposable | The domain is administered by a disposable email provider (e.g. Mailinator). |
| unknown | unknown | We were unable to conclusively verify or invalidate the email address. |
| timeout | The request timed out due to the host domain not responding in time. | |
| acceptAll | The domain is accept-all, so the email address cannot be validated. | |
| relayDenied | The result was validated at the incorrect mail exchanger. | |
| BLANK | You are submitting requests at a faster rate than allowed by the email service providers for the domains you are checking. |
| Name | Type | Description |
|---|---|---|
| first_name_match | string | Checks to see if the first name matches first names previously associated with that email. |
| last_name_match | string | Checks to see if the last name matches last names previously associated with that email. |
| address_line_1_match | string | Checks to see if the address line matches the address line previously associated with that email. |
| town_match | string | Checks to see if the town matches the town data previously associated with that email. |
| postal_code_match | string | Checks to see if the postal code matches the postal code data previously associated with that email. |
| deliverability | string | Checks if the address is deliverable. |
| deliverability_detail | string | Deliverable sub status. |
| address_type | string | Indicates the address type. |
| Name | Type | Description |
|---|---|---|
| routing_type | string | Indicates the IP Routing Type (IPRT), which specifies how the connection is routed through the Internet and can be used to determine how close the user is to the public IP address. |
| organization | string | The registering organization, which can include many types of entities, including corporate, government, or educational entities, and ISPs managing the allocation and use of network blocks. |
| proxy_type | string | The network or protocol utilized by the server to proxy the user connection is identified. |
| hosting_facility | boolean | A value of "true" indicates that the IP address is associated with a hosting facility; otherwise the value is "false". |
| latitude | number | The latitude of the identified location. |
| longtitude | number | The longitude of the identified location. |
The following response codes can be returned by the API:
| Status Code | Reason phrase | Description |
|---|---|---|
| 200 | Success | Request processed successfully. |
| 400 | Bad Request | Request failed due to malformed syntax. |
| 401 | Unauthorized | Auth-Token provided is incorrect. |
| 403 | Forbidden | Request is not authorized to use this service. |
| 404 | Not Found | Request is not found. |
| 406 | Not Acceptable | Request is not in an acceptable format. |
| 408 | Request Timeout | Response was not returned within the timeout allowance. |
| 415 | Unsupported Media Type | Request is not using a Media type that is recognized by the server. |
| 429 | Too many requests | Too many requests were sent. To protect all customers, your account has been temporarily throttled. Check our rate limiting for more details. |
| 500 | Internal Server Error | The server has encountered an error. |
| 503 | Service Unavailable | Service unavailable. Check service status for up-to-date information. |
{
"components": {
"first_name": [
"Joe"
],
"last_name": [
"Bloggs"
],
"address_line_1": [
"123 Main St"
],
"town": [
"New York"
],
"region": [
"NY"
],
"postal_code": [
"10000"
],
"email": [
"demo@experian.com"
],
"phone": [
"00123564789"
],
"country_iso_2": [
"US"
],
"ip_address": [
"255.255.255.255"
],
"user_agent": [
"python-requests/2.27.1"
]
},
"attributes": [
"risk"
]
}
{
"result": {
"risk": {
"score": 100,
"tumbling_risk": 3,
"domain_risk": 5
}
},
"metadata": {
"email_detail": {
"date_first_seen": "2016-08-09",
"longevity": 3,
"velocity": 10,
"popularity": 10,
"domain": {
"date_first_seen": "now",
"longevity": 3,
"velocity": 10,
"popularity": 10,
"domain_type": "freeisp"
},
"confidence": "verified",
"verbose_output": "verified",
"verbose_reason": "Valid email address."
},
"address_detail": {
"first_name_match": "match",
"last_name_match": "no_match",
"address_line_1_match": "no_data",
"town_match": "no_data",
"postal_code_match": "no_data",
"deliverability": "undeliverable",
"deliverability_detail": "missing_primary",
"address_type": {
"code": "S",
"description": "Street"
}
},
"ip_detail": {
"routing_type": "fixed",
"organization": "experian",
"proxy_type": "tor",
"hosting_facility": true,
"latitude": 38.89768,
"longitude": -77.03651
}
}
}