This page provides practical examples to help you understand how to use the List API for different scenarios and services.

For the examples below, the following CSV file will be used:

Email,First,Last,Address,City,State,Zip
emaila@example.com,John,Doe,100 Main St Apt 12B,Springfield,MA,01020
emailb@example.com,Mary,Smith,22 Clark Ave,Denton,TX,75065
emailc@example.com,Greg,Flynn,16 Park Ave,New York,NY,10016

Example 1: SafeToSend with full results processing

This example will exemplify using List API to send a list of emails for the SafeToSend service. Follow each API call below to submit a file, retrieve the list's status, and retrieve the results when they are processed.

📘
API key
Remember, to use List API for a particular service, you must use an API Key that has been enabled for that service.

Step 1: Submit a List File

Start by calling the Submit Lists endpoint and adding your API key and the necessary parameters. Find details on how to format your files in the File Formatting page of the docs. The code block below presents both the request and its successful response:

curl --request POST \
     --url 'https://api.atdata.com/v5/list?email_column=1&header=true&delimiter=%2C&action=process&name=file.csv' \
     --header 'Content-Type: multipart/form-data' \
     --header 'accept: application/json' \
     --header 'api_key: <YOUR_SAFETOSEND_API_KEY>' \
     --form file='@file.csv'

{
  "list_id": 1551515,
  "size_bytes": 228
}

Step 2: Checking the Status of the List

You need to wait until your results are ready. You can either use the callback_url parameter when you submit the list to be notified when the results are ready, or you can call the Check List Status endpoint to see when the results are done. Using the list_id returned in Step 1, you can check the status of your list. See the code below for the request and response:

curl --request GET \
     --url https://api.atdata.com/v5/list/1551515 \
     --header 'accept: application/json' \
     --header 'api_key: <YOUR_SAFETOSEND_API_KEY>'

{
  "list_id": 1551515,
  "name": "file.csv",
  "status": "Results",
  "records": 3,
  "size_bytes": 228,
  "created_at": "2024-08-13T13:37:29Z",
  "services": {
    "safetosend": {
      "input_count": 3,
      "completed_count": 3,
      "reporting": {
        "engagement": {
          "0": 0,
          "1": 0,
          "2": 0,
          "3": 0,
          "4": 0,
          "5": 0,
          "6": 0,
          "7": 0,
          "8": 0,
          "9": 0,
          "10": 0
        },
        "sts_status": {
          "SafeToSend": 0,
          "Valid": 0,
          "Invalid": 3,
          "Trap": 0,
          "Corrected": 0,
          "Unknown": 0
        },
        "sts_status_code": {
          "Timeout": 0,
          "Syntax OK": 0,
          "Syntax OK and domain valid": 0,
          "Domain does not support validation (accepts all mailboxes)": 0,
          "Valid email address": 0,
          "Address is allowed by client-configured exceptions": 0,
          "General syntax error": 0,
          "Invalid character in address": 0,
          "Invalid domain syntax": 0,
          "Invalid username syntax": 0,
          "Invalid username syntax for that domain": 0,
          "Address is too long": 0,
          "Address does not have a username": 0,
          "Address does not have a domain": 0,
          "Address does not have an @ sign": 0,
          "Address has more than one @ sign": 0,
          "Invalid top-level-domain (TLD) in address": 0,
          "Address contains space or extra text": 0,
          "Unquoted spaces are not allowed in email addresses": 0,
          "Address is not allowed by client-configured suppressions": 0,
          "Domain does not exist": 0,
          "Domain cannot receive email": 3,
          "Mailbox does not exist": 0,
          "Mailbox is full and can not receive email": 0,
          "Mail is not accepted for this domain": 0,
          "Emails with that username are not accepted": 0,
          "Emails with that domain are not accepted": 0,
          "That email address is not accepted": 0,
          "Address was rejected during our manual review process": 0,
          "The email address is known to bounce": 0,
          "Address is a spam trap or known complainer": 0,
          "Address has opted out from commercial email": 0,
          "Address is on ANA's \"Do Not Email List\"": 0,
          "Internal error": 0,
          "Address is a known complainer": 0
        },
        "sts_domain_type": {
          "Disposable": 0,
          "Free ISP": 0,
          "Paid ISP": 0,
          "Wireless": 0,
          "Education": 0,
          "Government": 0,
          "Business": 0,
          "Non-profit": 0,
          "Parked": 0,
          "Privacy": 0
        },
        "sts_role_account": {
          "Role Account": 0
        },
        "sts_invalid_category": {
          "Syntax Errors": 0,
          "Domain Errors": 3,
          "Mailbox Errors": 0,
          "Suppressions": 0
        },
        "sts_trap_hits": {
          "Trap Hits": 0
        }
      },
      "status": "Completed"
    }
  }
}

When the status is Results, it means your list is processed and purchased, and results can be downloaded.

See details about the possible status on the Check List Status Reports page.

Step 3: Retrieve the Results

After your list is processed, you need to retrieve the results. Call the Retrieve List Results endpoint, passing the list_id parameter to it to retrieve your results.

🚧
Purchasing Results
If, in Step 1, you sent the action parameter with a report value, you will need to purchase the results before retrieving it. Use the Purchase List Results endpoint before the Retrieve List Results request below.

curl --request GET \
     --url https://api.atdata.com/v5/list/1551515/results \
     --header 'accept: text/plain' \
     --header 'api_key: <YOUR_SAFETOSEND_API_KEY>'

Email,First,Last,Address,City,State,Zip,SafeToSend Status,SafeToSend Code,Domain Type,Role Account,Duplicate,Valid Email
emaila@example.com,John,Doe,100 Main St Apt 12B,Springfield,MA,01020,invalid,325,,,,
emailb@example.com,Mary,Smith,22 Clark Ave,Denton,TX,75065,invalid,325,,,,
emailc@example.com,Greg,Flynn,16 Park Ave,New York,NY,10016,invalid,325,,,,

After this, you have completed all the necessary steps to use the List API for executing the SafeToSend service. The same process can be used for all AtData services.

Example 2: Email Append with initial report before deciding to purchase

In some cases, you may want to check what the results of a service may be before deciding if you want to purchase the results. This example will exemplify using the List API to first generate a match report with the Email Append service and then optionally purchasing the results. Follow each API call below to submit a file, retrieve the list's status, and purchase and retrieve the results when they are processed.

📘
API key
Remember, to use List API for the Email Append service, you must use an API Key for that service.

Step 1: Submit a List File

Start by calling the Submit Lists endpoint with the action=report and all other necessary parameters. Find details on how to format your files in the File Formatting page of the docs. The code block below presents both the request and its successful response:

curl --request POST \
     --url 'https://api.atdata.com/v5/list?header=true&delimiter=%2C&action=report&name=file.csv' \
     --header 'Content-Type: multipart/form-data' \
     --header 'accept: application/json' \
     --header 'api_key: <YOUR_EMAIL_APPEND_API_KEY>' \
     --form file='@file.csv'

{
  "list_id": 1551554,
  "size_bytes": 169
}

Step 2: Checking the Status of the List

You need to wait until your results are ready. To check if they are completed, you can call the Check List Status endpoint. Using the list_id returned in Step 1, you can check the status of your list. See the code below for the request and response:

curl --request GET \
     --url https://api.atdata.com/v5/list/1551554 \
     --header 'accept: application/json' \
     --header 'api_key: <YOUR_EMAIL_APPEND_API_KEY>'

{
  "list_id": 1551554,
  "name": "file.csv",
  "status": "Processed",
  "records": 3,
  "size_bytes": 169,
  "created_at": "2024-08-13T14:17:27Z",
  "services": {
    "email_append": {
      "input_count": 3,
      "completed_count": 3,
      "reporting": {
        "email_match_type": {
          "Individual match": 1,
          "Household match": 0,
          "2nd Individual match": 0,
          "2nd Household match": 0,
          "3rd Individual match": 0,
          "3rd Household match": 0,
          "4th Individual match": 0,
          "4th Household match": 0,
          "5th Individual match": 0,
          "5th Household match": 0
        }
      },
      "status": "Completed"
    }
  }
}

The response will present a Processed status, indicating the results are ready but haven't been purchased. This is because, in Step 1, the action parameter was added with the report value to it, indicating you only wanted a report and were not ready to purchase the data. The response also includes a "reporting" section that describes what the service would return. In this case, there was one match at the Individual level.

See details about the possible statuses and the format of the reporting sections for each service on the Check List Status Reports page.

Step 3: Purchasing the Results

If the report shows results you want to obtain, you need to make a call to the Purchase List Results endpoint, indicating the list results you want to purchase by sending it's respective list_id:

curl --request POST \
     --url https://api.atdata.com/v5/list/1551554/purchase \
     --header 'accept: text/plain' \
     --header 'api_key: <YOUR_EMAIL_APPEND_API_KEY>' \
     --header 'content-type: application/json'

OK

Step 4: Retrieve the Results

Once you have purchased the results, you need to retrieve them. Call the Retrieve List Results endpoint, passing the list_id parameter to it to retrieve your results:

curl --request GET \
     --url https://api.atdata.com/v5/list/1551554/results \
     --header 'accept: text/plain' \
     --header 'api_key: <YOUR_EMAIL_APPEND_API_KEY>'

Email,First,Last,Address,City,State,Zip,SafeToSend Status,SafeToSend Code,Domain Type,Role Account,Duplicate,Valid Email
emaila@example.com,John,Doe,100 Main St Apt 12B,Springfield,MA,01020,invalid,325,,,,
emailb@example.com,Mary,Smith,22 Clark Ave,Denton,TX,75065,invalid,325,,,,
emailc@example.com,Greg,Flynn,16 Park Ave,New York,NY,10016,invalid,325,,,,

After this, you have completed all the necessary steps to use the List API to execute the Email Append service to get a report and then purchase results. This workflow can be used with all AtData services except SafeToSend. If you know that you will be using the results from the outset, skip the reporting step by omitting the action parameter or by using action=process as shown in the SafeToSend example at the top of this page.