{
  "openapi": "3.0.1",
  "info": {
    "title": "Email Append API - Demographics, Phones and Validation",
    "description": "Append an email address to a name and postal address, pull the age, income, household and interests behind an address, verify deliverability with a reason code and typo correction, find a person's other addresses, and check phone line type, carrier and connection status. Pay per result.",
    "version": "0.1",
    "x-build-id": "mGSamlKx4EPFTX81x"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/nabeelbaghoor~email-append-demographics-api/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-nabeelbaghoor-email-append-demographics-api",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/nabeelbaghoor~email-append-demographics-api/runs": {
      "post": {
        "operationId": "runs-sync-nabeelbaghoor-email-append-demographics-api",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/nabeelbaghoor~email-append-demographics-api/run-sync": {
      "post": {
        "operationId": "run-sync-nabeelbaghoor-email-append-demographics-api",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "mode": {
            "title": "What to look up",
            "enum": [
              "validate",
              "demographics",
              "emailAppend",
              "alternateEmail",
              "phone"
            ],
            "type": "string",
            "description": "Validate checks a list of addresses for deliverability and corrects typos. Demographics returns the household behind each address. Email append works out an address from a name and a postal address. Alternate email returns the other addresses belonging to the same person. Phone verification returns the line, carrier and connection status behind a number.",
            "default": "validate"
          },
          "emails": {
            "title": "Email addresses",
            "type": "array",
            "description": "Email addresses, one per line. Used by validation, demographics and alternate email. An address pasted inside a longer string, such as a mail header or a name and address pair, is extracted before the request.",
            "items": {
              "type": "string"
            }
          },
          "ipAddresses": {
            "title": "Signup IP addresses",
            "type": "array",
            "description": "Optional IP addresses the matching address signed up from, one per line, in the same order as the addresses above. The provider uses them to add country, state and connection type to the record. Leave empty when you do not have them. Validation only.",
            "items": {
              "type": "string"
            }
          },
          "fullNames": {
            "title": "Full names",
            "type": "array",
            "description": "Full names to append an address to, one per line. Each name is paired with the postal address on the same line below, because an append needs both halves of one person. A middle name is understood, and the last word is treated as the surname. Email append only.",
            "items": {
              "type": "string"
            }
          },
          "postalAddresses": {
            "title": "Postal addresses",
            "type": "array",
            "description": "One postal address per line, paired line by line with the names above, written as street, city, state, postcode. Both the four part and the three part spelling are understood, so 1 Main St, Boston, MA 02116 works as well as 1 Main St, Boston, MA, 02116. Email append only.",
            "items": {
              "type": "string"
            }
          },
          "phones": {
            "title": "Phone numbers",
            "type": "array",
            "description": "Phone numbers to verify, one per line. Brackets, dots and spaces are stripped before the request, so a pasted list in mixed formats still works. Phone verification only.",
            "items": {
              "type": "string"
            }
          },
          "phoneCountry": {
            "title": "Phone country code",
            "type": "string",
            "description": "Two letter ISO country code for the numbers above, such as US or GB. Set it when your numbers are written in national format without a country prefix. Leave empty when every number carries its own prefix. Phone verification only. For example US."
          },
          "statuses": {
            "title": "Keep only these verdicts",
            "type": "array",
            "description": "Only keep addresses with these verdicts. Restricting to the safe to send verdict is how you turn a raw list into one that is ready to mail. Leave empty to keep every verdict. Validation only, and applied after the provider answers, so it reduces dataset noise and Apify spend rather than provider credits.",
            "items": {
              "type": "string",
              "enum": [
                "safetosend",
                "valid",
                "invalid",
                "trap",
                "unknown",
                "corrected"
              ],
              "enumTitles": [
                "Safe to send: passed every check",
                "Valid: passed most checks, mailbox unconfirmed",
                "Invalid: bad syntax, dead domain or no mailbox",
                "Trap: valid but likely to trigger spam filters",
                "Unknown: checks could not be completed",
                "Corrected: a typo was found and fixed"
              ]
            },
            "default": []
          },
          "domainTypes": {
            "title": "Keep only these domain types",
            "type": "array",
            "description": "Only keep addresses whose domain falls into these categories. Restricting to business domains is the quickest way to strip consumer webmail out of a B2B list. Leave empty to keep every domain type. Validation only.",
            "items": {
              "type": "string",
              "enum": [
                "freeisp",
                "biz",
                "edu",
                "gov",
                "disposable",
                "wireless",
                "other"
              ],
              "enumTitles": [
                "Free consumer webmail",
                "Business domain",
                "Education domain",
                "Government domain",
                "Disposable address provider",
                "Wireless carrier domain",
                "Other"
              ]
            },
            "default": []
          },
          "excludeRoleAccounts": {
            "title": "Drop role accounts",
            "type": "boolean",
            "description": "Leave out shared inboxes such as info, sales and support, keeping only addresses that belong to an individual. Useful when the list is meant for one to one outreach. Validation only.",
            "default": false
          },
          "minQualityScore": {
            "title": "Minimum quality score",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "Only keep addresses scoring at least this on the provider's zero to ten engagement scale, which reflects how the mailbox behaves rather than whether it exists. Leave at zero to keep every score. Validation only.",
            "default": 0
          },
          "lineTypes": {
            "title": "Keep only these line types",
            "type": "array",
            "description": "Only keep numbers on these kinds of line. Restricting to mobile is how you build a list that can be texted. Leave empty to keep every line type. Phone verification only.",
            "items": {
              "type": "string",
              "enum": [
                "mobile",
                "landline",
                "voip",
                "unknown"
              ],
              "enumTitles": [
                "Mobile",
                "Landline",
                "Voice over IP",
                "Unknown"
              ]
            },
            "default": []
          },
          "minConnectedScore": {
            "title": "Minimum connected score",
            "minimum": 0,
            "maximum": 100,
            "type": "integer",
            "description": "Only keep numbers scoring at least this on the provider's zero to one hundred connected scale, which is its confidence that the line is live and dialable. Above seventy means high confidence it is connected. United States numbers only. Leave at zero to keep every score. Phone verification only.",
            "default": 0
          },
          "timeout": {
            "title": "Validation timeout in seconds",
            "minimum": 1,
            "maximum": 30,
            "type": "integer",
            "description": "How long the provider may spend on one address before answering unknown. Raising it resolves more of the slow mail servers at the cost of a longer run. The provider's own ceiling is thirty seconds. Validation only.",
            "default": 10
          },
          "requestsPerMinute": {
            "title": "Requests per minute",
            "minimum": 1,
            "maximum": 1200,
            "type": "integer",
            "description": "Pace the run so it stays under whatever rate your plan allows. Lower this if the provider starts returning rate limit responses; raise it to finish a long list sooner.",
            "default": 300
          },
          "skipNotFound": {
            "title": "Skip inputs with no result",
            "type": "boolean",
            "description": "Leave inputs the provider had nothing for out of the dataset. Off by default, because keeping the misses is what lets you see which inputs resolved and which did not. Misses are never charged for either way.",
            "default": false
          },
          "maxResults": {
            "title": "Maximum results",
            "minimum": 1,
            "maximum": 50000,
            "type": "integer",
            "description": "Stop after this many rows. This is the cap on both spend and run time.",
            "default": 100
          },
          "apiKey": {
            "title": "API key",
            "type": "string",
            "description": "Your own API key for the email intelligence API. This provider accepts the key only as a request parameter, so the actor keeps it out of every log line instead. Required for every lookup. Stored as a secret."
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}