This page provides practical examples to help you understand how the Retrieve Fraud Prevention API responds under different scenarios. These examples illustrate a variety of possible requests with their corresponding responses, showing how the API behaves with complete and partial data inputs, as well as handling incorrect or missing information.

Each example provides insight into how the API processes and responds to various inputs, aiding developers in effectively integrating and troubleshooting the Retrieve Fraud Prevention API.

For the examples, unless specified differently, the data used is as follows:

Parameter	Example data
`api_key`	`<YOUR_API_KEY>`
`email`	`example@atdata.com`
`reference_id`	`123_456_789`
`first`	`John`
`last`	`Doe`
`street`	`123 Main St`
`city`	`New York`
`state`	`NY`
`zip`	`123456`
`country`	`US`
`phone`	`123456789`
`ip`	`1.2.3.4`
`user_agent`	`python-requests F2.27.1`

Example 1: Complete Data, Unlikely Fraud

This example demonstrates a request with all data fields filled, which returns a 200 response and indicates that fraud is unlikely.

curl --request GET \
     --url 'https://api.atdata.com/fr?api_key=<YOUR_API_KEY>&email=example%40atdata.com&reference_id=123_456_789&first=John&last=Doe&street=123%20Main%20St&city=New%20York&state=NY&zip=123456&country=US&phone=123456789&ip=1.2.3.4&user_agent=python-requests%20F2.27.1' \
     --header 'accept: application/json'

{
  "eam": {
    "longevity": 3,
    "velocity": 10,
    "date_first_seen": "2017-04-21",
    "popularity": 10
  },
  "dam": {
    "longevity": 3,
    "velocity": 7,
    "date_first_seen": "2011-07-27",
    "popularity": 8
  },
  "risk": {
    "score": 2,
    "query_id": "47b1b085-1ced-4697-8fba-cb98db09709d",
    "tumbling_risk": 0,
    "ip": {
      "routing_type": "fixed",
      "organization": "atdata",
      "latitude": 40.42094,
      "proxy_type": "",
      "hosting_facility": false,
      "longitude": 73.59250
    },
    "domain": {
      "domain_risk_score": 0
    },
    "postal": {
      "deliverability": "deliverable",
      "address_type": "Street",
      "last_name_match": "match",
      "first_name_match": "match",
      "deliverability_substatus": "deliverable",
      "zip_match": "match",
      "city_match": "match",
      "street_match": "match"
    },
    "phone": {
      "line_type": "mobile",
      "carrier": "AT&T Wireless",
      "status": "live",
      "prepaid": false,
      "owner": {
        "first_name_match": "match",
        "last_name_match": "match",
        "street_match": "match",
        "city_match": "match",
        "zip_match": "match",
        "type": "person"
      }
    }
  },
  "safe_to_send": {
    "status_code": 50,
    "address": "example@atdata.com",
    "status": "safetosend"
  }
}

Example 2: Complete Data, Likely Fraud

Here, a request is sent with complete data similar to the first example, but it returns a 200 response that indicates a likely fraudulent email. This example helps with understanding how different data inputs can affect fraud assessment.

curl --request GET \
     --url 'https://api.atdata.com/fr?api_key=<YOUR_API_KEY>&email=example%40atdata.com&reference_id=123_456_789&first=John&last=Doe&street=123%20Main%20St&city=New%20York&state=NY&zip=123456&country=US&phone=123456789&ip=1.2.3.4&user_agent=python-requests%20F2.27.1' \
     --header 'accept: application/json'

{
  "eam": {
    "longevity": 1,
    "velocity": 1,
    "date_first_seen": "2024-02-16",
    "popularity": 0
  },
  "dam": {
    "longevity": 1,
    "velocity": 6,
    "date_first_seen": "2003-06-08",
    "popularity": 5
  },
  "risk": {
    "score": 94,
    "query_id": "2746f8b4-4337-4710-b2c3-50bd54a710a4",
    "tumbling_risk": 2,
    "domain": {
      "domain_risk_score": 7
    },
    "postal": {
      "deliverability": "possibly_deliverable",
      "address_type": "Highrise",
      "last_name_match": "no_data",
      "first_name_match": "no_data",
      "deliverability_substatus": "missing_secondary",
      "zip_match": "no_data",
      "city_match": "no_data",
      "street_match": "no_data"
    },
    "phone": {
      "line_type": "voip",
      "carrier": "Onvoy Spectrum, LLC",
      "status": "live",
      "prepaid": false,
      "owner": {
        "first_name_match": "no_match",
        "last_name_match": "no_match",
        "street_match": "no_match",
        "city_match": "no_match",
        "zip_match": "no_match",
        "type": "person"
      }
    }
  },
  "safe_to_send": {
    "domain_type": "biz",
    "status_code": 45,
    "address": "example@atdata.com",
    "status": "valid"
  }
}

Example 3: Email Only, Unlikely Fraud

This request includes only the email address, returns a 200 response, and suggests that fraud is unlikely, showcasing how the API handles minimal data inputs.

curl --request GET \
     --url 'https://api.atdata.com/fr?api_key=<YOUR_API_KEY>&email=example%40atdata.com' \
     --header 'accept: application/json'

{
  "eam": {
    "longevity": 3,
    "velocity": 0,
    "date_first_seen": "2011-04-04",
    "popularity": 0
  },
  "dam": {
    "longevity": 3,
    "velocity": 10,
    "date_first_seen": "2002-11-09",
    "popularity": 10
  },
  "risk": {
    "score": 1,
    "query_id": "9aef8719-e1cf-4a1e-afea-9e2764b716d0",
    "tumbling_risk": 0,
    "domain": {
      "domain_risk_score": 0
    }
  },
  "safe_to_send": {
    "domain_type": "freeisp",
    "status_code": 50,
    "address": "example@atdata.com",
    "status": "safetosend"
  }
}

Example 4: Email Only, Likely Fraud

Similar to the previous one, this example involves a request with just an email address but returns a 200 response where fraud is deemed likely, helping users see how the API evaluates risk based solely on email.

curl --request GET \
     --url 'https://api.atdata.com/fr?api_key=<YOUR_API_KEY>&email=example%40atdata.com' \
     --header 'accept: application/json'

{
  "eam": {
    "longevity": 0,
    "velocity": 0,
    "date_first_seen": "now",
    "popularity": 0
  },
  "dam": {
    "longevity": 2,
    "velocity": 0,
    "date_first_seen": "2024-02-09",
    "popularity": 0
  },
  "risk": {
    "score": 99,
    "query_id": "9aef8719-e1cf-4a1e-afea-9e2764b716d0",
    "tumbling_risk": 0,
    "domain": {
      "domain_risk_score": 10
    }
  },
  "safe_to_send": {
    "status_code": 50,
    "address": "example@atdata.com",
    "status": "safetosend"
  }
}

Example 5: Incorrectly Filled Email, Email Correction

A request with an incorrectly filled email address that returns a 200 response, including a suggestion of possible email address correction. It illustrates the API’s ability to suggest corrections to possible incorrectly informed emails. In this example, the email is incorrectly typed as example@atdata.co.

curl --request GET \
     --url 'https://api.atdata.com/fr?api_key=<YOUR_API_KEY>&email=example%40atdata.co' \
     --header 'accept: application/json'

{
  "eam": {
    "longevity": 0,
    "velocity": 0,
    "date_first_seen": "now",
    "popularity": 0
  },
  "dam": {
    "longevity": 0,
    "popularity": 0,
    "velocity": 0
  },
  "risk": {
    "score": 100,
    "query_id": "a789df02-5b11-4361-a740-b778708c4595",
    "tumbling_risk": 0,
    "domain": {
      "domain_risk_score": 10
    }
  },
  "safe_to_send": {
    "status_code": 325,
    "address": "example@atdata.co",
    "email_corrections": [
      "example@atdata.com"
    ],
    "status": "invalid"
  }
}

Example 6: Incorrect Email, Invalid Status

This example presents a request with an incorrect email address that yields a 200 response, which returns an invalid status for the email address. This example demonstrates how the system deals with invalid email addresses for which it does not have a suggestion for correction. In this example, the email was filled in as notanactualemail.

curl --request GET \
     --url 'https://api.atdata.com/fr?api_key=<YOUR_API_KEY>&email=notanactualemail' \
     --header 'accept: application/json'

{
  "safe_to_send": {
    "status_code": 150,
    "address": "notanactualemail",
    "status": "invalid"
  }
}

Example 7: Missing Email

Shows a request submitted without an email address, resulting in a 400 response for a missing query parameter, highlighting how the API enforces required fields.

curl --request GET \
     --url 'https://api.atdata.com/fr?api_key=<YOUR_API_KEY>' \
     --header 'accept: application/json'

Missing query parameter(s).

Example 8: Incorrect API Key

This example shows a request made with an incorrect API key that leads to a 401 response, indicating an invalid API key. In this example, the API key is <INVALID_API_KEY>.

curl --request GET \
     --url 'https://api.atdata.com/fr?api_key=\<INVALID_API_KEY>&email=example%40atdata.com' \
     --header 'accept: application/json'

Invalid API key.